Name

dced_server_stop - Stops a DCE-configured server running on a specific host

Synopsis

#include <dce/dced.h> void dced_server_stop(
dced_binding_handle_t dced_bh,
uuid_t ∗exec_uuid,
srvrexec_stop_method_t method,
error_status_t ∗status);

Parameters

Input

dced_bhSpecifies the dced binding handle for the srvrexec service on a specific host. 

exec_uuidSpecifies a UUID that dced uses to identify the running server.  If the value input is dced_g_uuid_all_servers, dced attempts to stop all the DCE servers running on that host. 

methodSpecifies the method dced uses to stop a server.  A method is represented by one of the following values:

srvrexec_stop_rpc
Uses the rpc_mgmt_stop_server_listening() routine.  This is the cleanest way to stop a server, because it waits for outstanding remote procedure calls to finish before making the server’s rpc_server_listen() routine return. 

srvrexec_stop_soft
Uses a “soft” local host mechanism (such as the TERM signal in UNIX)

srvrexec_stop_hard
Uses a “hard” local host mechanism (such as the KILL signal in UNIX)

srvrexec_stop_error
Uses a mechanism that saves the program state (such as the ABORT signal in UNIX)

Output

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not. 

Description

The dced_server_stop() routine stops DCE-configured servers on specific hosts.  When the server is completely stopped and no longer a running process, dced deletes the associated execution data it maintained. 

Administrators use the dcecp operations server create and server start to configure and start a server, and management applications use the associated dced_server_create() and dced_server_start() routines. 

Prior to calling dced_server_stop(), the application must have established a valid dced binding handle to the srvrexec service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). 

Cautions

Using the value dced_g_uuid_all_servers for the exec_uuid parameter causes dced to shutdown all servers including itself. 

Examples

The following example obtains dced binding handles to the server configuration and execution services of dced on the host patrick.  The example then checks to see if the server is running by seeing if dced has a UUID and entry for the executing server.  However, the server may be in the process of starting up or stopping, so the example also checks to be sure the instance UUID of the running server matches the UUID of the configuration for that server.  If there is a match, the server is running.  Finally, the example stops the server by calling dced_server_stop() with the srvrexec_stop_rpc parameter. 

dced_binding_handle_t conf_bh, exec_bh;
dced_string_t         server_name;
void                  ∗data;
server_t              ∗exec_ptr;
uuid_t                srvrconf_id, srvrexec_id;
error_status_t        status;
 .
 .
 .
dced_binding_create("srvrconf@hosts/patrick",
                    dced_c_binding_syntax_default,
                    &conf_bh,
                    &status);
dced_binding_create("srvrexec@hosts/patrick",
                    dced_c_binding_syntax_default,
                    &exec_bh,
                    &status);
    /∗ is server running? ∗/
dced_inq_id(exec_bh, server_name, &srvrexec_id, &status);
    /∗ also check to be sure server is not coming up or going down ∗/
dced_object_read(exec_bh, &srvrexec_id, &data, &status);
exec_ptr = (server_t∗)data;
dced_inq_id(conf_bh, server_name, &srvrconf_id, &status);
if(uuid_equal(&srvrconf_id,
              &exec_ptr->exec_data.tagged_union.running_data.instance,
              &status) ) {
    dced_server_stop(exec_bh, &srvrexec_id, srvrexec_stop_rpc, &status);
}
dced_objects_release(exec_bh, 1, data, &status);
dced_binding_free(conf_bh, &status);
dced_binding_free(exec_bh, &status);

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

error_status_ok

dced_s_bad_binding

dced_s_no_support

dced_s_not_found

rpc_s_binding_incomplete

rpc_s_comm_failure

rpc_s_invalid_binding

rpc_s_mgmt_op_disallowed

rpc_s_unknown_if

rpc_s_wrong_kind_of_binding

sec_acl_invalid_permission

uuid_s_bad_version

Related Information

dcecp Objects: server(8dce). 

Functions: dced_binding_create(3dce), dced_binding_from_rpc_binding(3dce), dced_server_create(3dce) dced_server_start(3dce), rpc_mgmt_stop_server_listening(3rpc). 

Books: OSF DCE Application Development Guide.