Partner domain’s specific gates

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

PTTW gate, CREATE_POOL function

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

PTTW gate, DESTROY_POOL function

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

PTTW gate, QUERY_POOL function

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

PTTW gate, START_POOL_BROWSE function

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

PTTW gate, GET_NEXT_POOL function

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

PTTW gate, END_POOL_BROWSE function

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

PTTW gate, CREATE_PARTNERSHIP function

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

PTTW gate, DESTROY_PARTNERSHIP function

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

PTTW gate, SET_USER_TOKEN function

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

PTTW gate, INQUIRE_USER_TOKEN function

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

PTTW gate, MAKE_PARTNERSHIP function

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

PTTW gate, BREAK_PARTNERSHIP function

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

PTTW gate, TRIGGER_PARTNER function

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

PTTW gate, WAIT_FOR_PARTNER function

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

PTTW gate, QUERY_PARTNERSHIP function

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

PTTW gate, SET_GARBAGE_INTERVAL function

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

PTTW gate, INQUIRE_GARBAGE_INTERVAL function

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