NAME

tt_enumerated_types - Introduction to ToolTalk enumerated types

Tt_address

Possible Values for Tt_address

Value

Description

TT_HANDLER

Addressed to a specific handler that can perform this operation with these arguments. Fill in handler, op ,and arg attributes of the message or pattern.

TT_OBJECT

Addressed to a specific object that performs this operation with these arguments. Fill in object, op ,and arg attributes of the message or pattern.

TT_OTYPE

Addressed to the type of object that can perform this operation with these arguments. Fill in otype, op ,and arg attributes of the message or pattern.

TT_PROCEDURE

Addressed to any process that can perform this operation with these arguments. Fill in the op and arg attributes of the message or pattern.

Tt_callback

Possible Values for Tt_callback

Value                            Description

TT_CALLBACK_CONTINUE

If the callback returns TT_CALLBACK_CONTINUE,

other callbacks will be run.

TT_CALLBACK_PROCESSED

If the callback returns

TT_CALLBACK_PROCESSED, no further callbacks

will be invoked for this event, and the message will

not be returned by tt_message_receive().

Tt_category

Possible Values for Tt_category

Value                      Description

TT_OBSERVE

Just looking at the message. No feedback will be given to the sender.

TT_HANDLE_PUSH

Like TT_HANDLE, but will pick the most recently registered pattern given several equally qualified choices

TT_HANDLE_ROTATE

Like TT_HANDLE, but if there are no TT_HANDLE_PUSH patterns, pick the least recently used TT_HANDLE_ROTATE pattern before trying TT_HANDLE patterns.

TT_HANDLE

Will process the message, including filling in return values if any.

Tt_class

Possible Values for Tt_class

Value            Description
TT_NOTICE        Notice of an event. Sender does not want feedback on this message.

TT_OFFER

The term "offer" was chosen because the effect is like passing a plate of goodies around -- everybody takes one if they want; when the plate comes back you know everybody's been offered one.

TT_REQUEST

Request for some action to be taken. Sender must be notified of progress, success or failure, and must receive any return values.

Tt_disposition

Possible Values for Tt_disposition

Value            Description

TT_DISCARD

No receiver for this message. Message is returned to sender with the Tt_status field containing TT_FAILED.

TT_QUEUE

Queue the message until a process of the proper ptype receives the message.

TT_START

Attempt to start a process of the proper ptype if none is running.

Tt_feature

Possible Values for Tt_feature

Value

Description

TT_FEATURE_MULTITHREADED

Indicates that this version of the ToolTalk API

can support multi threaded ToolTalk API calls.

TT_FEATURE_LAST

This code should be unused.

Tt_filter

Possible Values for Tt_filter

Value                       Description
TT_FILTER_CONTINUE          Continue the query, feed more values to the callback.
TT_FILTER_STOP              Stop the query, don't look for any more values.

Tt_mode

Possible Values for Tt_mode

Value         Description

TT_IN

The argument is written by the sender and read by the handler and any observers.

TT_OUT

The argument is written by the handler and read by the sender and any reply observers.

TT_INOUT

The argument is written by the sender and the handler and read by all.

Tt_scope

Possible Values for Tt_scope

Value                    Description

TT_SESSION

All processes joined to the indicated session are eligible.

TT_FILE

All processes joined to the indicated file are eligible.

TT_BOTH

All processes joined to either the indicated file or the indi-

cated session are eligible.

TT_FILE_IN_SESSION

All processes joined to both the indicated session and the

indicated file are eligible.

Tt_state

Possible Values for Tt_state

Value

Description

TT_ABSTAINED

Offers (only) enter this state when a receiving procid does the next tt_message_receive without accepting or rejecting the offer. One can think of TT_ABSTAINED also being entered when a procid destroys an offer without accepting or rejecting it, but since the message is destroyed at that time the procid will never see the state. This state is seen only by the receiver.

TT_ACCEPTED

Offers (only) enter this state when tt_message_accept is done on them by a receiver. The state is seen only by the receiver.

TT_CREATED

Message has been created but not yet sent.

TT_SENT

Message has been sent but not yet handled.

TT_HANDLED

Message has been handled, return values are valid.

TT_FAILED

Message could not be delivered to a handler.

TT_QUEUED

Message has been queued for later delivery.

TT_RETURNED

All observers (and the handler, if there is one) have accepted, rejected, or destroyed the TT_OFFER. The original sender sees this state, and it can be observed.

This comes back to the original sender like the reply for a request. In particular, any message callbacks for the offer are run, and user data attached to the message before sending are available.

TT_STARTED

Attempting to start a process to handle the message.

TT_REJECTED

Message has been rejected by a possible handler. This state is seen only by the rejecting process. The ToolTalk service changes the state back to TT_SENT before delivering the message to another possible handler. If all possible handlers have rejected the message, the ToolTalk service changes the state to TT_FAILED before

returning the message to the sender. A receiver that gets an offer will see this message in the TT_REJECTED state.

Tt_status

A Tt_status code is returned by all functions, sometimes directly and sometimes encoded in an error return value. See the ToolTalk 1.3 User's Guide for instructions on to determine whether the Tt_status code is a warning or an error and for retrieving the error message string for a Tt_status code.

The following section lists the Tt_status codes.

Error Messages

TT_ERR_ACCESS

Error Message String:

TT_ERR_ACCESS

An attempt was made to access a ToolTalk object in a way forbidden by the protection system.

Description:

You do not have the necessary access to the object and the application; for example, you do not have permission to destroy an object spec. Therefore, the operation cannot be performed.

Solution:

a. Obtain proper access to the object.

b. Retry the operation.

TT_ERR_ADDRESS

Error Message String:

TT_ERR_ADDRESS

The Tt_address value passed is not valid.

Description:

The ToolTalk service does not recognize the address value specified.

Solution:

The Tt_address values are TT_PROCEDURE, TT_OBJECT, TT_HANDLER, and TT_OTYPE. Retry the call with one of these values.

TT_ERR_APPFIRST

Error Message String:

TT_ERR_APPFIRST

This code should be unused.

Description:

This code marks the beginning of the messages allocated for ToolTalk application errors.

Solution:

NA

TT_ERR_CATEGORY

Error Message String:

TT_ERR_CATEGORY

Pattern object has no category set.

Description:

The category was not set.

Solution:

NA

TT_ERR_CLASS

Error Message String:

TT_ERR_CLASS

The Tt_class value passed is invalid.

Description:

The ToolTalk service does not recognize the class value specified.

Solution:

The Tt_class values are TT_NOTICE and TT_REQUEST. Retry the call with one of these values.

TT_ERR_DBAVAIL

Error Message String:

TT_ERR_DBAVAIL

A required database is not available. The condition may be temporary, trying again later may work.

Description:

The ToolTalk service could not access the ToolTalk database needed for this operation.

Solution:

a. Check if the file server or workstation that contains the database is available. b. Try the operation again later.

TT_ERR_DBCONSIST

Error Message String:

Database is access information is incomplete or database is corrupt (run ttdbck).

Description:

The ToolTalk service could not write to the database because it is either corrupt, or the access inform

Solution:

Run the ttdbck utility to repair the database.

TT_ERR_DBEXIST

Error Message String:

TT_ERR_DBEXIST

A required database does not exist. The database must be created before this action will work.

Description:

The ToolTalk service did not find the specified ToolTalk database in the expected place.

Solution:

Install the rpc.ttdbserved program on the machine that stores the file or object involved in this operation.

TT_ERR_DBFULL

Error Message String:

ToolTalk database is full.

Description:

The ToolTalk service could not write to the database because it is full.

Solution:

Create more space on the file system in which the database is stored.

TT_ERR_DBUPDATE

Error Message String:

TT_ERR_DBUPDATE

The database is inconsistent: another tt_spec_write updated object first.

Description:

The ToolTalk service could not update the database because the specified object was already updated by a previous tt_spec_write call.

Solution:

NA

TT_ERR_DISPOSITION

Error Message String:

TT_ERR_DISPOSITION

The Tt_disposition value passed is not valid.

Description:

The disposition passed is not recognized by the ToolTalk service.

Solution:

The Tt_disposition values are TT_DISCARD, TT_QUEUE, and TT_START. Retry the call with one of these values.

TT_ERR_FILE

Error Message String:

TT_ERR_FILE

File object could not be found.

Description:

The file specified does not exist or is not accessible.

Solution:

a. Check the file path name and retry the operation.

b. Check if the machine where the file is stored is accessible.

TT_ERR_INTERNAL

Error Message String:

TT_ERR_INTERNAL

Internal error (bug)

Description:

The ToolTalk service has suffered an internal error.

Solution:

a. Restart all applications that are using the ToolTalk service. b. Report the error to the your system vendor support center.

TT_ERR_LAST

Error Message String:

TT_ERR_LAST

This code should be unused.

Description:

This code marks the last of the messages allocated for ToolTalk errors.

Solution:

NA

TT_ERR_MODE

Error Message String:

TT_ERR_MODE

The Tt_mode value is not valid.

Description:

The ToolTalk service does not recognize the specified mode value.

Solution:

The Tt_mode values are TT_IN, TT_OUT, and TT_INOUT. Retry the call with one of these values.

TT_ERR_NO_MATCH

Error Message String:

TT_ERR_NO_MATCH

No handler could be found for this message, and the disposition was not queue or start.

Description:

The message the application sent could not be delivered.

No applications that are running have registered interest in this type of message.

Solution:

Use tt_disposition_set() to change the disposition to TT_QUEUE or TT_START and resend the message.

If no recipients are found, no application has registered interest in this type of message.

TT_ERR_NO_VALUE

Error Message String:

TT_ERR_NO_VALUE

No property value with the given name and number exists.

Description:

The ToolTalk service could not locate a value for the property specified in the ToolTalk database.

Solution:

Retrieve the current list of properties to find the property.

TT_ERR_NOMEM

Error Message String:

No more memory.

Description:

There is not enough available memory to perform the operation.

Solution:

Check the swap space, then retry the operation.

TT_ERR_NOMP

Error Message String:

TT_ERR_NOMP

No ttsession process is running, probably because tt_open() has not been called yet. If this code is returned from tt_open() it means ttsession could not be started, which generally means ToolTalk is not installed on this system.

Description:

The ttsession process is not available. The ToolTalk service tries to restart ttsession if it is not running. This error indicates that the ToolTalk service is either not installed or not installed correctly.

Solution:

a. Verify that the ToolTalk service is installed.

b. Verify that ttsession is installed on the machine in use.

TT_ERR_NOTHANDLER

Error Message String:

TT_ERR_NOTHANDLE

Only the handler of the message can do this.

Description:

Only the handler of a message can perform this operation. This application is not the handler for this message.

Solution:

NA

TT_ERR_NUM

Error Message String:

TT_ERR_NUM

The integer value passed is not valid.

Description:

An invalid integer value that was out-of-range was passed to the ToolTalk service.

Note: Simple out-of-range conditions, such as requesting the third value of a property that has only two values, return a null value.

Solution:

Check the integer specified.

TT_ERR_OBJID

Error Message String:

TT_ERR_OBJID

The object id passed does not refer to any existing object spec.

Description:

The objid does not reference an existing object.

Solution:

Update the spec property that contains the objid specified.

TT_ERR_OP

Error Message String:

TT_ERR_OP

The operation name passed is not syntactically valid.

Description:

The specified operation name is null or contains non-alphanumeric characters.

Solution:

a. Remove any non-alphanumeric characters.

b. Retry the operation.

TT_ERR_OTYPE

Error Message String:

TT_ERR_OTYPE

The object type passed is not the name of an installed object type.

Description:

The ToolTalk service could not locate the specified otype.

Solution:

Check the type of the object with tt_spec_type(). If the application was recently installed and the ToolTalk service has not reread the ToolTalk Types Database: a. Locate the process id for the ttsession.

b. Force the reread with the USR-2 signal:

% ps -elf | grep ttsession

% kill -USR2 <ttsession pid>

TT_ERR_OVERFLOW

Error Message String:

TT_ERR_OVERFLOW

Too many active messages (try again later).

Description:

The ToolTalk service has received the maximum amount of active messages (2000) it can properly handle.

Solution:

Either:

a. Retrieve any messages that the ToolTalk service may be queueing for the application, and send the message again later.

b. Start ttsession with the -A option. Specify the maximum number of messages in progress before a TT_ERR_OVERFLOW

condition is returned. The default is 2000 messages.

TT_ERR_PATH

Error Message String:

TT_ERR_PATH

One of the directories in the file path passed does not exist or cannot be read.

Description:

The ToolTalk service was not able to read a directory in the specified file path name.

Solution:

a. Check the pathname to ensure access to the specified directories. b. Check the machine where the file resides to make sure it is accessible.

TT_ERR_POINTER

Error Message String:

TT_ERR_POINTER

The opaque pointer (handle) passed does not indicate an object of the proper type.

Description:

The pointer passed does not point at an object of the correct type for this operation. For example, the pointer may point to an integer when a character string is needed.

Solution:

a. Check the arguments for the ToolTalk function to find what arguments the function expects.

b. Retry the operation with a pointer for a valid object.

TT_ERR_PROCID

Error Message String:

TT_ERR_PROCID

The process id passed is not valid.

Description:

The process identifier specified is out of date or invalid.

Solution:

Retrieve the default procid with tt_default_procid().

TT_ERR_PROPLEN

Error Message String:

TT_ERR_PROPLEN

The property value passed is too long.

Description:

The ToolTalk service accepts property values of up to 64 characters.

Solution:

Shorten the property value to less than 64 characters.

TT_ERR_PROPNAME

Error Message String:

TT_ERR_PROPNAME

The property name passed is syntactically invalid.

Description:

The property name is too long, contains non-alphanumeric

Solution:

Check the property name, modify if necessary, and retry the operation.

TT_ERR_PTYPE

Error Message String:

TT_ERR_PTYPE

The process type passed is not the name of an installed process type.

Description:

The ToolTalk service could not locate the specified ptype.

Solution:

If the application was recently installed and the ToolTalk service has not reread the ToolTalk Types Database:

a. Locate the process id for the ttsession.

b. Force the reread with the USR-2 signal:

% ps -elf | grep

ttsession

% kill -USR2

<ttsession pid>

TT_ERR_PTYPE_START

Error Message String:

TT_ERR_PTYPE_START

Attempt to launch a client specified in the start attribute of a ptype failed.

Description:

The ToolTalk service could not start the type of process specified.

Solution:

Verify that the application that the ptype represents is properly installed and has execute permission.

TT_ERR_READONLY

Error Message String:

TT_ERR_READONLY

The attribute cannot be changed.

Description:

The application does not have ownership or write permissions for the attribute. Therefore, this operation cannot be performed.

Solution:

NA

TT_ERR_SCOPE

Error Message String:

TT_ERR_SCOPE

The Tt_scope value passed is not valid.

Description:

The scope passed is not recognized by the ToolTalk service.

Solution:

The Tt_scope values are TT_SESSION and TT_FILE. Retry the call with one of these values.

TT_ERR_SESSION

Error Message String:

TT_ERR_SESSION

The session id passed is not the name of an active session.

Description:

An out-of-date or invalid ToolTalk session was specified.

Solution:

Either:

a. obtain the sessid of the current default session using tt_default_session() b. obtain the sessid of the initial session in which the application was started using tt_initial_session()

TT_ERR_SLOTNAME

Error Message String:

The slot name is syntactically invalid.

Description:

The syntax for the slot name is not valid.

Solution:

Correct the syntax for the slot name.

TT_ERR_STATE

Error Message String:

The Tt_message is in a state that is not valid for the attempted operation.

Description:

The state of the message is invalid for the type of operation being requested.

Solution:

NA

TT_ERR_TOOLATE

Error Message String:

This must be the first call made into the ToolTalk API and can therefore no longer be performed.

Description:

This error will be returned from ToolTalk API calls which require that a specific call be made into the API before any other call is made (such as is the case with use of the ToolTalk multi-thread API calls).

Solution:

NA

TT_ERR_UNIMP

Error Message String:

TT_ERR_UNIMP

Function not implemented.

Description:

The ToolTalk function called is not implemented.

Solution:

NA

TT_ERR_VTYPE

Error Message String:

TT_ERR_VTYPE

The value type name passed is not valid.

Description:

The specified property exists in the ToolTalk database but the type of value does not match the specified type; or the value type is not one that the ToolTalk service recognizes. The ToolTalk service supports types of int and string.

Solution:

a. Change the type of the value to either int or string.

b. Retry the operation.

TT_ERR_XDR

Error Message String:

The XDR procedure failed on the given data, or evaluated to a 0 length structure.

Description:

The XDR procedure failed on the given data, or evaluated to a 0 length structure.

Solution:

NA

TT_OK

Error Message String:

TT_OK

Request successful.

Description:

The call was completed successfully.

Solution:

NA

TT_STATUS_LAST

Error Message String:

TT_STATUS_LAST

This code should be unused.

Description:

This code marks the last of the messages allocated for ToolTalk status.

Solution:

NA

TT_WRN_APPFIRST

Error Message String:

TT_WRN_APPFIRST

This code should be unused.

Description:

This code marks the beginning of the messages allocated for ToolTalk application warnings.

Solution:

NA

TT_WRN_LAST

Error Message String:

TT_WRN_LAST

This code should be unused.

Description:

This code marks the last of the messages allocated for ToolTalk warnings.

Solution:

NA

TT_WRN_NOT_ENABLED

Error Message String:

TT_WRN_NOT_ENABLED

The ToolTalk feature has not been enabled yet in this process.

Description:

This warning can be returned from certain ToolTalk API calls if a particular optional feature of the ToolTalk API (such as multi-threading) has not yet been enabled.

Solution:

NA

TT_WRN_NOTFOUND

Error Message String:

TT_WRN_NOTFOUND

The object was not removed because it was not found.

Description:

The ToolTalk service could not find the specified object in the ToolTalk database. The destroy operation did not succeed.

Solution:

NA

TT_WRN_SAME_OBJID

Error Message String:

TT_WRN_SAME_OBJID

The moved object retains the same objid.

Description:

The object moved stayed within the same file system. The ToolTalk service will retain the same objid and update the location.

Solution:

NA

TT_WRN_STALE_OBJID

Error Message String:

TT_WRN_STALE_OBJID

The object attribute in the message has been replaced with a newer one. Update

the place from which the object id was obtained.

Description:

When the ToolTalk service looked up the specified object in the ToolTalk database, it found a forwarding pointer to the object.

Solution:

The ToolTalk service automatically puts the new objid in the message. a. Use tt_message_object() to retrieve the new objid.

b. Update any internal application references to the new objid.

TT_WRN_START_MESSAGE

Error Message String:

TT_WRN_START_MESSAGE

This message caused this process to be started. This message should be replied to even if it is a notice.

Description:

When the ToolTalk service starts an application to deliver a message to it, a reply to that message must be sent even if the message which ToolTalk is attempting to deliver is a notice.

Solution:

Use tt_message_accept() or tt_message_reply() to reply to, fail, or reject the message after the process is started by the ToolTalk service.

TT_WRN_STOPPED

Error Message String:

TT_WRN_STOPPED

The query was halted by the filter procedure.

Description:

The query operation being performed was halted by the Tt_filter_function.

Solution:

NA

tt_enumerated_types ( 1 ) modified 1 March 1996

ToolTalk 1.3

1-15