Table 84 summarizes the PT domain’s specific gates. It
shows the level-1 trace point IDs of the modules providing the functions for
the gates, the functions provided by the gates, and whether or not the functions
are available through the exit programming interface (XPI).
Table 84. Partner domain’s specific gates
Gate |
Trace |
Function |
XPI |
PTTW |
OT 0100
OT 0101
|
CREATE_POOL
DESTROY_POOL
QUERY_POOL
START_POOL_BROWSE
GET_NEXT_POOL
END_POOL_BROWSE
CREATE_PARTNERSHIP
DESTROY_PARTNERSHIP
SET_USER_TOKEN
INQUIRE_USER_TOKEN
MAKE_PARTNERSHIP
BREAK_PARTNERSHIP
TRIGGER_PARTNER
WAIT_FOR_PARTNER
QUERY_PARTNERSHIP
SET_GARBAGE_INTERVAL
INQUIRE_GARBAGE_INTERVAL
|
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
NO
|
The CREATE_POOL function creates a pool for state_tokens.
Input parameters
- POOL_NAME
- The eight character name of the pool. This name must be unique across
all pools. There is no enforced character set for this name.
- GARBAGE_COLLECTION
- Whether or not garbage collection is to be performed for state_tokens
in this pool. It can have either of these two values:
ON|OFF
- [GARBAGE_COLLECT_INTERVAL]
- The interval in milliseconds between collections of garbage for this
pool. If garbage collection is on, this parameter must be provided. If garbage
collection is off, this parameter is ignored.
- [FREE_USER_DATA_DOMAIN]
- An optional callback routine that may be called to free any user data
addressed from the user_data_token associated with each state_token. This
callback must implement the PTFD FREE_USER_DATA gate.
- [FREE_USER_DATA_GATE]
- An optional callback routine that may be called to free any user data
addressed from the user_data_token associated with each state_token. This
callback must implement the PTFD FREE_USER_DATA gate.
Output parameters
- POOL_TOKEN
- The token of this pool
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NAME_NOT_UNIQUE
BAD_CALLBACK
|
Destroys a pool of state_tokens.
Input parameters
- POOL_TOKEN
- The token of this pool
- DESTROY_OPTION
- Specifies how the pool is destroyed. It can have any of these values:
MUST_BE_EMPTY|FORCE|QUIESCE
Output parameters
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
POOL_NOT_EMPTY
POOL_NOT_FOUND
POOL_QUIESCING
|
Query the attributes and state of a pool.
Input parameters
- [POOL_NAME]
- The eight character name of the pool. This name must be unique across
all pools. There is no enforced character set for this name.
- [POOL_TOKEN]
- The token of this pool
Output parameters
- [POOL_NAME_OUT]
- The pool name is returned.
- [POOL_TOKEN_OUT]
- The pool token is returned.
- [POOL_STATE]
- The cureent state of the pool. It can have any of these values:
EMPTY|NOT_EMPTY|QUIESCING
- [GARBAGE_COLLECTION]
- Whether or not garbage collection is to be performed for state_tokens
in this pool. It can have either of these two values:
ON|OFF
- [GARBAGE_COLLECT_INTERVAL]
- The interval in milliseconds between collections of garbage for this
pool. If garbage collection is on, this parameter must be provided. If garbage
collection is off, this parameter is ignored.
- [FREE_USER_DATA_DOMAIN]
- An optional callback routine that may be called to free any user data
addressed from the user_data_token associated with each state_token. This
callback must implement the PTFD FREE_USER_DATA gate.
- [FREE_USER_DATA_GATE]
- An optional callback routine that may be called to free any user data
addressed from the user_data_token associated with each state_token. This
callback must implement the PTFD FREE_USER_DATA gate.
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
POOL_NOT_FOUND |
Creates a pool cursor to browse pools.
Output parameters
- POOL_CURSOR
- The browse cursor returned from start_pool_browse
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NO_POOLS |
Get the next pool
Input parameters
- POOL_CURSOR
- The browse cursor returned from start_pool_browse
Output parameters
- [POOL_TOKEN]
- The token of this pool
- [POOL_NAME]
- The eight character name of the pool. This name must be unique across
all pools. There is no enforced character set for this name.
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
END_BROWSE
INVALID_CURSOR
|
End a browse of pools.
Input parameters
- POOL_CURSOR
- The browse cursor returned from start_pool_browse
Output parameters
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
INVALID_CURSOR |
Create a new state block to represent a partnership, and add it to the
pool.
Input parameters
- POOL_TOKEN
- The token of this pool
Output parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
POOL_NOT_FOUND
POOL_QUIESCING
|
Remove a state block from its pool and delete it to destroy the partnership.
If the state token is still in use by the partner, it is flagged as deleted.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
Output parameters
- [OLD_TRIGSTATE1]
- The state of partner 1 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [OLD_TRIGSTATE2]
- The state of partner 2 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE1]
- The state of partner 1 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE2]
- The state of partner 2 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_FOUND
PARTNER_WAITING
|
Change the user token in the state block.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- USER_TOKEN
- The user token to be associated with the state token
Output parameters
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_FOUND |
Get the user token in the state block.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
Output parameters
- USER_TOKEN
- The user token to be associated with the state token
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_FOUND |
Establish a partnership with another task. The partner task may or may
not have previously made the partnership.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- ORDER
- Specifies the order in which the partners make the partnership. It can
have any of these values:
DONT_CARE|ONLY|SUBSEQUENT
Output parameters
- [OLD_TRIGSTATE1]
- The state of partner 1 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [OLD_TRIGSTATE2]
- The state of partner 2 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE1]
- The state of partner 1 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE2]
- The state of partner 2 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_ONLY
NOT_SUBSEQUENT
ALREADY_MADE
ALREADY_PARTNER
NOT_FOUND
NOT_PARTNER
|
Break an established partnership.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- [COMPLETION_CODE]
- The completion code to be passed to the partner. The caller can use
this to notify partner why the partnership is being broken. Once read the
completion code is reset to zero. This is optional so that the caller can
pass exactly one completion code when calling trigger_partner followed by
break_partnership. The completion code is ignored if the resulting state is
not_made.
Output parameters
- [OLD_TRIGSTATE1]
- The state of partner 1 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [OLD_TRIGSTATE2]
- The state of partner 2 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE1]
- The state of partner 1 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE2]
- The state of partner 2 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- PARTNER_COMPLETION_CODE
- The partner's completion code indicates why the partner broke the partnership.
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_PARTNER
NOT_FOUND
PARTNERSHIP_NOT_MADE
|
Notify a waiting partner. If the partner is not actually waiting when trigger
is called, the partner will be triggered when it next waits.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- COMPLETION_CODE
- The completion code to be passed to the partner.
- PARTNER_EXISTENCE
- Specifies whether the partner must exist for this request. It can have
either of these two values:
DONT_CARE|MUST_EXIST
Output parameters
- [OLD_TRIGSTATE1]
- The state of partner 1 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [OLD_TRIGSTATE2]
- The state of partner 2 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE1]
- The state of partner 1 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE2]
- The state of partner 2 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NAME_NOT_UNIQUE
BAD_CALLBACK
|
Wait to be notified by a partner or until the wait times out.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
- PARTNER_EXISTENCE
- Specifies whether the partner must exist for this request. It can have
either of these two values:
DONT_CARE|MUST_EXIST
- [TIMEOUT]
- An optional maximum time to wait before waking up in milliseconds
- [PURGEABLE]
- Specifies whether the wait can be purged. It can have either of these
two values:
YES|NO
Output parameters
- PARTNER_COMPLETION_CODE
- The partner's completion code indicates why the partner broke the partnership.
- [OLD_TRIGSTATE1]
- The state of partner 1 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [OLD_TRIGSTATE2]
- The state of partner 2 before the request. It can have any of these
values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE1]
- The state of partner 1 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [NEW_TRIGSTATE2]
- The state of partner 2 after the request. It can have any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NAME_NOT_UPARTNERSHIP_NOT_MADE
NOT_PARTNER
TIMED_OUT
NOT_FOUND
PARTNER_WAITING
PARTNER_NOT_THERENIQUE
BAD_CALLBACK
|
Get the status of the partner task.
Input parameters
- STATE_TOKEN
- The state_token used to manage the handshake
Output parameters
- [XM_TOKEN]
- The partner's transaction manager token.
- [POOL_TOKEN]
- The token of this pool
- [STATE]
- Describes whether the state token is not made, made or partially made
and who by. It can have any of these values:
NOT_MADE|MADE_BY_PARTNER|MADE_BY_SELF|MADE
- [STATUS_OF_PARTNER]
- Describes whether partner is waiting or has been triggered. It can have
any of these values:
UNDEFINED|VALID|TRIGGERED|WAITING|RESUMED
- [STATUS_OF_SELF]
- Describes whether the caller has been triggered or not. It can have
any of these values:
UNDEFINED|VALID|TRIGGERED
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NOT_PARTNER
NOT_FOUND
|
Set garbage collection interval.
Input parameters
- POOL_TOKEN
- The token of this pool
- GARBAGE_COLLECT_INTERVAL
- The interval in milliseconds between collections of garbage for this
pool. If garbage collection is on, this parameter must be provided. If garbage
collection is off, this parameter is ignored.
Output parameters
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
GARBAGE_COLLECTION_OFF
POOL_NOT_FOUND
|
Get garbage collection interval.
Input parameters
- POOL_TOKEN
- The token of this pool
Output parameters
- GARBAGE_COLLECTION
- Indicates whether or not garbage collection is to be performed for state_tokens
in this pool. It can have either of these two values:
ON|OFF
- GARBAGE_COLLECT_INTERVAL
- The interval in milliseconds between collections of garbage for this
pool. If garbage collection is on, this parameter must be provided. If garbage
collection is off, this parameter is ignored.
- RESPONSE
- is the domain’s response to the call. It can have any of these
values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
- [REASON]
- is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE |
Possible REASON values |
EXCEPTION |
NAME_NOT_UNIQUE
BAD_CALLBACK
|
[[ Contents Previous Page | Next Page Index ]]