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_bh
       Specifies the dced binding handle for the srvrexec service
       on a specific host.

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

   method
       Specifies 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

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if
       not, why not.  The possible status codes are:

            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

 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 );

 RELATED INFORMATION

   Routines:   dced_server_create
               dced_server_start
               rpc_mgmt_stop_server_listening
               dced_binding_create
               dced_binding_from_rpc_binding

   dcecp Objects: server

   Books: OSF DCE Application Development Guide.