Joint Client/Servers

CORBA Programming Reference

start_persistent_userid

Synopsis

Activates an object, sets the ORB and the POA to the proper state, and returns an object reference to the activated object.

IDL

Object start_persistent_userid(
              portableServer::Servant     a_servant,
              in CORBA::RepositoryId      rep_id,
              in string                   stroid) 
    raises ( ServantAlreadyActive, ObjectAlreadyActive );

C++ Binding

CORBA::Object_ptr start_persistent_userid (
               PortableServer::Servant    servant, 
               const char*                rep_id,
               const char*                stroid);

Arguments

servant

An instance of the C++ implementation class for the interface.

rep_id

The repository ID of the interface.

stroid

The stringified version of an ObjectId provided by the user to be set in the object reference being created. The stroid holds application-specific data and is opaque to the ORB.

Exceptions

ServantAlreadyActive

The servant is already being used for a callback. A servant can be used only for a callback with a single ObjectId. To receive callbacks on objects containing different ObjectIds, you must create different servants and activate them separately. The same servant can be reused only if a stop_object operation tells the system to stop using the servant for its original ObjectId.

ObjectAlreadyActive

The stringified ObjectId is already being used for a callback. A given ObjectId can have only one servant associated with it. If you wish to change to a different servant, you must first invoke stop_object with the servant currently in use.

CORBA::BAD_PARAM

The repository ID was a NULL string or the servant was a NULL pointer.

CORBA::IMP_LIMIT

In addition to other system reasons for this exception, a reason unique to this situation is that the joint client/server was not initialized with a port number; therefore, a persistent object reference cannot be created.

Description

This operation performs the following actions:

Activates an object using the Servant supplied to service objects of the type rep_id, using the object Id stroid.
Sets the ORB and the POA into the state in which they will accept requests on that object.
Returns an object reference to the activated object. The returned object reference will be valid even after termination of the client. That is, if the client terminates, and restarts again, and then activates a servant with the same rep_id and for the same ObjectId, the servant will accept requests made on that same object reference.

Return Value

CORBA::Object_ptr

An object reference created with the stringified ObjectId stroid and the rep_id provided by the user. The object reference will need to be converted to a specific object type by invoking the _narrow() operation defined for the specific object. The caller is responsible for releasing the object when the conversion is done.