Provided by: libglobus-gram-client-doc_14.6-3build2_all bug

NAME

       globus_gram_client_job_functions - GRAM Job Functions

        - GRAM Job Functions.

SYNOPSIS

   Functions
       int globus_gram_client_register_ping (const char *resource_manager_contact,
           globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Send a ping request to a GRAM service.
       int globus_gram_client_ping (const char *resource_manager_contact)
           Send a ping request to a GRAM service.
       int globus_gram_client_get_jobmanager_version (const char *resource_manager_contact,
           globus_hashtable_t *extensions)
           Get version information from a job manager.
       int globus_gram_client_register_get_jobmanager_version (const char
           *resource_manager_contact, globus_gram_client_attr_t attr,
           globus_gram_client_info_callback_func_t info_callback, void *callback_arg)
           Get version information from a job manager without blocking.
       int globus_gram_client_register_job_request (const char *resource_manager_contact, const
           char *description, int job_state_mask, const char *callback_contact,
           globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Send a job request to a GRAM service.
       int globus_gram_client_job_request (const char *resource_manager_contact, const char
           *description, int job_state_mask, const char *callback_contact, char **job_contact)
           Send a job request to a GRAM service.
       int globus_gram_client_register_job_request_with_info (const char
           *resource_manager_contact, const char *description, int job_state_mask, const char
           *callback_contact, globus_gram_client_attr_t attr,
           globus_gram_client_info_callback_func_t callback, void *callback_arg)
           Send a job request to a GRAM service with extensions-aware callback.
       int globus_gram_client_job_request_with_info (const char *resource_manager_contact, const
           char *description, int job_state_mask, const char *callback_contact, char
           **job_contact, globus_gram_client_job_info_t *info)
           Send a job request to a GRAM service and parse extensions in the response.
       int globus_gram_client_job_cancel (const char *job_contact)
           Cancel a GRAM job.
       int globus_gram_client_register_job_cancel (const char *job_contact,
           globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Cancel a GRAM job.
       int globus_gram_client_job_signal (const char *job_contact,
           globus_gram_protocol_job_signal_t signal, const char *signal_arg, int *job_status, int
           *failure_code)
           Send a signal a GRAM job.
       int globus_gram_client_register_job_signal (const char *job_contact,
           globus_gram_protocol_job_signal_t signal, const char *signal_arg,
           globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Send a signal a GRAM job.
       int globus_gram_client_job_status (const char *job_contact, int *job_status, int
           *failure_code)
           Send a status query to a GRAM job.
       int globus_gram_client_register_job_status (const char *job_contact,
           globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Send a status query to a GRAM job.
       int globus_gram_client_register_job_status_with_info (const char *job_contact,
           globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback,
           void *callback_arg)
           Send a status query to a GRAM job.
       int globus_gram_client_job_status_with_info (const char *job_contact,
           globus_gram_client_job_info_t *info)
           Send a status query to a GRAM job.
       int globus_gram_client_job_callback_register (const char *job_contact, int job_state_mask,
           const char *callback_contact, int *job_status, int *failure_code)
           Register a new callback contact to be notified for job state changes.
       int globus_gram_client_job_callback_unregister (const char *job_contact, const char
           *callback_contact, int *job_status, int *failure_code)
           Unregister a callback contact to stop job state change notifications.
       int globus_gram_client_job_refresh_credentials (char *job_contact, gss_cred_id_t creds)
           Delegate a new credential to a job.
       int globus_gram_client_register_job_refresh_credentials (char *job_contact, gss_cred_id_t
           creds, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
           register_callback, void *register_callback_arg)
           Delegate a new credential to a job.
       int globus_gram_client_register_job_callback_registration (const char *job_contact, int
           job_state_mask, const char *callback_contact, globus_gram_client_attr_t attr,
           globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg)
           Register a new callback contact to be notified for job state changes.
       int globus_gram_client_register_job_callback_unregistration (const char *job_contact,
           const char *callback_contact, globus_gram_client_attr_t attr,
           globus_gram_client_nonblocking_func_t register_callback, void *register_callback_arg)
           Unregister a callback contact to stop job state change notifications.

Detailed Description

       GRAM Job Functions.

Function Documentation

   int globus_gram_client_get_jobmanager_version (const char * resource_manager_contact,
       globus_hashtable_t * extensions)
       Get version information from a job manager. The
       globus_gram_client_get_jobmanager_version() function sends a message to a GRAM service
       which returns information about the job manager version in the value pointed to by the
       extensions parameter. Note that job managers prior to GT5 do not support the version
       request and so will return a GLOBUS_GRAM_PROTOCOL_ERROR_HTTP_UNPACK_FAILED error. This
       function blocks while processing this request.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact.
           extensions A pointer to a hash table which will be initialized to contain the version
           information returned by the service. The extensions defined by GRAM5 are toolkit-
           version and version.

       Returns
           Upon success, globus_gram_client_get_jobmanager_version() function returns
           GLOBUS_SUCCESS and modifies the extensions parameter as described above. If an error
           occurs, the integer error code will be returned and the value pointed to by the
           extensions parameter is undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_BAD_GATEKEEPER_CONTACT Bad gatekeeper contact
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER NULL parameter
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol failed
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_callback_register (const char * job_contact, int job_state_mask,
       const char * callback_contact, int * job_status, int * failure_code)
       Register a new callback contact to be notified for job state changes. The
       globus_gram_client_job_callback_register() function contacts a GRAM service managing a job
       and instructs it to send subsequent job state callbacks to the client listening for
       callbacks at the contact url named by the callback_contact parameter. This function blocks
       until the registration operation either completes or exits.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A URL string containing a GRAM client callback. This string is
           normally be generated by a process calling globus_gram_client_callback_allow().
           job_status An output parameter pointing to an integer to set to the status of the job
           after the registration message has been processed.
           failure_code An output parameter that points to an integer to be set to the reason why
           the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. If the
           job has not failed, the value will be set to 0.

       Returns
           Upon success, the globus_gram_client_job_callback_register() function returns
           GLOBUS_SUCCESS, sends a registration request the job named by job_contact and parses
           the service response, modifying the values pointed to by the job_status and
           failure_code parameters as described above. If an error occurs,
           globus_gram_client_job_callback_register() returns an integer error code indicating
           why it can't register the callback contact. The return code may be any value defined
           by the globus_gram_protocol_error_t enumeration in addition to those listed below.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_callback_unregister (const char * job_contact, const char *
       callback_contact, int * job_status, int * failure_code)
       Unregister a callback contact to stop job state change notifications. The
       globus_gram_client_job_callback_unregister() function contacts a GRAM service managing a
       job and instructs it to stop sending job state callbacks to the client listening for
       callbacks at the contact url named by the callback_contact parameter. This function blocks
       until the unregistration operation either completes or exits. It is possible that
       callbacks related to the job arrive at the contact after this function returns depending
       on network delays.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           callback_contact A URL string containing a GRAM client callback. This string is
           normally be generated by a process calling globus_gram_client_callback_allow().
           job_status An output parameter pointing to an integer to set to the status of the job
           after the registration message has been processed.
           failure_code An output parameter that points to an integer to be set to the reason why
           the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. If the
           job has not failed, the value will be set to 0.

       Returns
           Upon success, the globus_gram_client_job_callback_unregister() function returns
           GLOBUS_SUCCESS, sends an unregister request the job named by job_contact and parses
           the service response, modifying the values pointed to by the job_status and
           failure_code parameters as described above. If an error occurs,
           globus_gram_client_job_callback_unregister() returns an integer error code indicating
           why it can't unregister the callback contact. The return code may be any value defined
           by the globus_gram_protocol_error_t enumeration in addition to those listed below.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_cancel (const char * job_contact)
       Cancel a GRAM job. The globus_gram_client_job_cancel() function cancels a GRAM job.
       Depending on the job's current state, this cancellation may be immediate or require a
       delay for interacting with the LRM servicing the job. Notification when the job has been
       successfully canceled will be sent to all client contacts registered for notifications
       after the cancellation has been completely processed. Unlike,
       globus_gram_client_register_job_cancel(), globus_gram_client_job_cancel() blocks until the
       job cancel request has been processed by the service.

       Parameters
           job_contact A NULL-terminated character string containing a GRAM job contact that this
           function will contact to cancel the job.

       Returns
           Upon succes, globus_gram_client_job_cancel() returns GLOBUS_SUCCESS if the
           cancellation was successful posted to the service. If an error occurs,
           globus_gram_client_job_cancel() returns one of the #globus_gram_protocol_error_t
           values values indicating why the client could not cancel the job.

       See also
           globus_gram_client_register_job_cancel()

   int globus_gram_client_job_refresh_credentials (char * job_contact, gss_cred_id_t creds)
       Delegate a new credential to a job. The globus_gram_client_job_refresh_credentials()
       function sends a 'renew' signal to a GRAM service and then initiates the delegation of a
       new credential to the job manager and job. This prevents errors that can occur when a
       credential expires. This function blocks until the delegation has completed or failed.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           creds A GSSAPI credential handle which will be used to authenticate with the job
           manager and sign the delegated credential. This parameter's value may be set to
           GSS_C_NO_CREDENTIAL to indicate the desire to use this process's default credential.

       Returns
           Upon success, the globus_gram_client_job_refresh_credentials() function returns
           GLOBUS_SUCCESS, sends an proxy renew request the job named by job_contact, parses the
           service response and performs a GSSAPI delegation to send a new credential to the job
           service. If an error occurs, globus_gram_client_job_refresh_credentials() returns an
           integer error code indicating why it can't refresh the job service's credential. The
           return code may be any value defined by the globus_gram_protocol_error_t enumeration
           in addition to those listed below.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_request (const char * resource_manager_contact, const char *
       description, int job_state_mask, const char * callback_contact, char ** job_contact)
       Send a job request to a GRAM service. The globus_gram_client_job_request() function sends
       a GRAM protocol message to a service to request that it start a job on behalf of the
       client. Unlike, globus_gram_client_register_job_request(),
       globus_gram_client_job_request() blocks until the job request has been processed by the
       service.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.
           description A pointer to a string containing the job request information formatted in
           RSL syntax.
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A GRAM listener contact that the job manager will send job state
           notification messages to.
           job_contact An output parameter pointing to a string that will be set to the job
           contact for this job. This value will only be set if the job request is successful or
           the two-phase commit protocol is being used and the return code is
           GLOBUS_GRAM_PROTOCOL_ERROR_WAITING_FOR_COMMIT.

       Returns
           Upon success, globus_gram_client_job_request() returns GLOBUS_SUCCESS and modifies the
           value pointed to by job_contact as described above. If an error occurs, this function
           returns an integer error code and the value pointed to by job_contact. In addition to
           the error codes described below, any #globus_gram_protocol_error_t value may be
           returned as a cause for the job to fail.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_request_with_info (const char * resource_manager_contact, const
       char * description, int job_state_mask, const char * callback_contact, char **
       job_contact, globus_gram_client_job_info_t * info)
       Send a job request to a GRAM service and parse extensions in the response. The
       globus_gram_client_job_request_with_info() function sends a GRAM protocol message to a
       service to request that it start a job on behalf of the client. Unlike,
       globus_gram_client_register_job_request_with_info(),
       globus_gram_client_job_request_with_info() blocks until the job request has been processed
       by the service.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.
           description A pointer to a string containing the job request information formatted in
           RSL syntax.
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A GRAM listener contact that the job manager will send job state
           notification messages to.
           job_contact An output parameter pointing to a string that will be set to the job
           contact for this job. This value will only be set if the job request is successful or
           the two-phase commit protocol is being used and the return code is
           GLOBUS_GRAM_PROTOCOL_ERROR_WAITING_FOR_COMMIT.
           info An output parameter pointing to a structure to hold the extensions in the GRAM
           response. The caller is responsible for destroying this by calling the
           globus_gram_client_job_info_destroy() function.

       Returns
           Upon success, globus_gram_client_job_request_with_info() returns GLOBUS_SUCCESS and
           modifies the values pointed to by job_contact and info as described above. If an error
           occurs, this function returns an integer error code and the value pointed to by
           job_contact. In addition to the error codes described below, any
           #globus_gram_protocol_error_t value may be returned as a cause for the job to fail.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_signal (const char * job_contact, globus_gram_protocol_job_signal_t
       signal, const char * signal_arg, int * job_status, int * failure_code)
       Send a signal a GRAM job. The globus_gram_client_job_signal() function sends a signal
       message to a job managed by the GRAM service. Signals consist of a signal number and an
       optional string argument. The meanings of the signals supported by the GRAM job manager
       are defined in the GRAM Protocol documentation. Unlike
       globus_gram_client_register_job_signal(), this function blocks until the signal has been
       delivered and acknowledged by the GRAM service.

       Parameters
           job_contact The job contact string of the job manager to contact. This is the same
           value returned from globus_gram_client_job_request().
           signal The signal code to send to the job manager.
           signal_arg Parameters for the signal, as described in the documentation for the
           #globus_gram_protocol_job_signal_t enumeration.
           job_status An output parameter pointing to an integer to set to the status of the job
           after the signal has been processed.
           failure_code An output parameter pointing to an integer to set to the reason why the
           job has failed if the value pointed to by job_status is set to
           GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED by this function.

       Returns
           Upon success, globus_gram_client_job_signal() returns GLOBUS_SUCCESS after sending the
           signal and receiving a response and modifies the job_status and failure_code
           parameters as described above. If an error occurs, this function returns an integer
           error code indicating why the client could not signal the job.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

       See also
           globus_gram_client_register_job_signal()

   int globus_gram_client_job_status (const char * job_contact, int * job_status, int *
       failure_code)
       Send a status query to a GRAM job. The globus_gram_client_status() function queries the
       current status of the job associated with the job contact, returning its current status,
       as well as the job's failure reason if it has failed in this function's return parameters.
       This function blocks until the service has responded to the status query.

       Parameters
           job_contact The job contact string of the job to query. This is the same value
           returned from globus_gram_client_job_request().
           job_status An output parameter that points to an integer to be set to the current
           status of the job named by the job_contact parameter.
           failure_code An output parameter that points to an integer to be set to the reason why
           the job failed if its current status is GLOBUS_GRAM_PROTOCOL_JOB_STATE_FAILED. If the
           job has not failed, the value will be set to 0.

       Returns
           Upon success, the globus_gram_client_job_status() function returns GLOBUS_SUCCESS,
           sends a job state query to the job named by job_contact and parses the service
           response, modifying the values pointed to by job_status and failure_code as described
           above. If an error occurs, globus_gram_client_job_status() returns an integer error
           code.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_job_status_with_info (const char * job_contact,
       globus_gram_client_job_info_t * info)
       Send a status query to a GRAM job. The globus_gram_client_status_with_info() function
       queries the current status of the job associated with the job contact, returning its
       current status, as well as the job's failure reason if it has failed in this function's
       return parameters. This function blocks until the service has responded to the status
       query.

       Parameters
           job_contact The job contact string of the job to query. This is the same value
           returned from globus_gram_client_job_request().
           info An output parameter that points to a globus_gram_client_job_info_t structure
           which will be populated with the state information associated with the job named by
           the job_contact parameter. The caller is responsible for calling
           globus_gram_client_job_info_destroy() to free the state pointed to by this parameter
           if this function returns GLOBUS_SUCCESS.

       Returns
           Upon success, the globus_gram_client_job_status_with_info() function returns
           GLOBUS_SUCCESS, sends a job state query to the job named by job_contact and parses the
           service response, modifying the structure pointed to by info as described above. If an
           error occurs, globus_gram_client_job_status_with_info() returns an integer error code.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_ping (const char * resource_manager_contact)
       Send a ping request to a GRAM service. The globus_gram_client_ping() function sends a
       specially-formatted GRAM protocol message which checks to see if a Gatekeeper is running
       on a given PORT, and whether that Gatekeeper is configured to support the desired job
       manager service. This is used for diagnostic purposes.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.

       Returns
           Upon success, globus_gram_client_ping() contacts the gatekeeper service and returns
           GLOBUS_SUCCESS. If an error occurs, this function returns an integer error code.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_register_get_jobmanager_version (const char * resource_manager_contact,
       globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback,
       void * callback_arg)
       Get version information from a job manager without blocking. The
       globus_gram_client_register_get_jobmanager_version() function sends a message to a GRAM
       service which returns information about the job manager version to the function pointed to
       by the info_callback function. Note that job managers prior to GT5 do not support the
       version request and so will return a GLOBUS_GRAM_PROTOCOL_ERROR_HTTP_UNPACK_FAILED error.
       This function blocks while processing this request.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact.
           attr A set of client attributes to use to contact the gatekeeper. If no custom
           attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           info_callback A pointer to a function to call when the version request has completed
           or failed.
           callback_arg A pointer to application-specific data which will be passed to the
           function pointed to by info_callback as its user_callback_arg parameter.

       Returns
           Upon success, globus_gram_client_register_get_jobmanager_version() function returns
           GLOBUS_SUCCESS and begins processing the version request to contact
           resource_manager_contact; when complete, the info_callback function will be called. If
           an error occurs, the integer error code will be returned and the value pointed to by
           the extensions parameter is undefined.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_BAD_GATEKEEPER_CONTACT Bad gatekeeper contact
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER NULL parameter
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol failed
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_register_job_callback_registration (const char * job_contact, int
       job_state_mask, const char * callback_contact, globus_gram_client_attr_t attr,
       globus_gram_client_nonblocking_func_t register_callback, void * register_callback_arg)
       Register a new callback contact to be notified for job state changes. The
       globus_gram_client_register_job_callback_registration() function initiates the protocol to
       contact a GRAM service and request that it send subsequent job state callbacks to the
       client listening for callbacks at the contact url named by the callback_contact parameter.
       This function returns as soon as it has validated its parameters and begun sending the
       GRAM message. When the registration is complete, the function pointed to by
       register_callback is called.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A URL string containing a GRAM client callback. This string is
           normally be generated by a process calling globus_gram_client_callback_allow().
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the registration request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, the globus_gram_client_register_job_callback_registration() function
           returns GLOBUS_SUCCESS, begins to send a registration request to the job named by
           job_contact, and schedules the register_callback to be called once the registration
           completes or fails. If an error occurs, this function returns an integer error code
           indicating why it can't process the request.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

       See also
           globus_gram_client_job_callback_register()

   int globus_gram_client_register_job_callback_unregistration (const char * job_contact, const
       char * callback_contact, globus_gram_client_attr_t attr,
       globus_gram_client_nonblocking_func_t register_callback, void * register_callback_arg)
       Unregister a callback contact to stop job state change notifications. The
       globus_gram_client_register_job_callback_unregistration() function initiates the protocol
       to contact a GRAM service and request that it stop sending job state callbacks to the
       client listening at the contact url named by the callback_contact parameter. This function
       returns as soon as it has validated its parameters and begun sending the GRAM message.
       When the unregistration is complete, the function pointed to by register_callback is
       called.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           callback_contact A URL string containing a GRAM client callback. This string is
           normally be generated by a process calling globus_gram_client_callback_allow().
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the registration request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, the globus_gram_client_register_job_callback_unregistration() function
           returns GLOBUS_SUCCESS, begins sending an unregister request to the job named by
           job_contact and schedules the function pointed to by the register_callback parameter
           to be called. If an error occurs,
           globus_gram_client_register_job_callback_unregistration() returns an integer error
           code indicating why it can't process the unregister request.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

       See also
           globus_gram_client_job_callback_unregister()

   int globus_gram_client_register_job_cancel (const char * job_contact,
       globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback,
       void * register_callback_arg)
       Cancel a GRAM job. The globus_gram_client_register_job_cancel() function sends a message
       to a GRAM service to cancel a GRAM job. Depending on the job's current state, this
       cancellation may be immediate or require a delay for interacting with the LRM servicing
       the job. In either case, this function returns as soon as it is able to start sending the
       message. Notification when the job has been successfully canceled will be sent to all
       client contacts registered for notifications after the cancellation has been completely
       processed.

       Parameters
           job_contact A NULL-terminated character string containing a GRAM job contact that this
           function will contact to cancel the job.
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the job_request request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon succes, globus_gram_client_register_job_cancel() returns GLOBUS_SUCCESS if the
           cancellation was successful posted to the service. If an error occurs,
           globus_gram_client_register_job_cancel() returns one an integer error code indicating
           why it could not cancel the job.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

       See also
           globus_gram_client_job_cancel()

   int globus_gram_client_register_job_refresh_credentials (char * job_contact, gss_cred_id_t
       creds, globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t
       register_callback, void * register_callback_arg)
       Delegate a new credential to a job. The
       globus_gram_client_register_job_refresh_credentials() function sends a 'renew' signal to a
       GRAM service and then initiates the delegation of a new credential to the job manager and
       job. This prevents errors that can occur when a credential expires. This function returns
       as soon as it has determined that its parameters are valid and it has begun to send the
       message to the GRAM service.

       Parameters
           job_contact The job contact string of the job to contact. This is the same value
           returned from globus_gram_client_job_request().
           creds A GSSAPI credential handle which will be used to authenticate with the job
           manager and sign the delegated credential. This parameter's value may be set to
           GSS_C_NO_CREDENTIAL to indicate the desire to use this process's default credential.
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the status request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, the globus_gram_client_job_refresh_credentials() function returns
           GLOBUS_SUCCESS and begins sending the 'renew' request to the GRAM service. If an error
           occurs, globus_gram_client_job_refresh_credentials() returns an integer error code
           indicating why it can't refresh the job service's credential. The return code may be
           any value defined by the globus_gram_protocol_error_t enumeration in addition to those
           listed below.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_register_job_request (const char * resource_manager_contact, const char
       * description, int job_state_mask, const char * callback_contact,
       globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback,
       void * register_callback_arg)
       Send a job request to a GRAM service. The globus_gram_client_register_job_request()
       function sends a GRAM protocol message to a service to request that it start a job on
       behalf of the client.

       If globus_gram_client_register_job_request() determines that this request could not be
       processed before contacting the gatekeeper (for example, a malformed
       resource_manager_contact), it will return an error, and the regiser_callback function will
       not be called. Otherwise, the success or failure an be determined by the
       operation_failure_code parameter to the function pointed to by the register_callback
       parameter.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.
           description A pointer to a string containing the job request information formatted in
           RSL syntax.
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A GRAM listener contact that the job manager will send job state
           notification messages to.
           attr A set of client attributes to use to contact the gatekeeper. If no custom
           attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the job_request request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, globus_gram_client_register_job_request() returns GLOBUS_SUCCESS and the
           register_callback function will be called once the job request operation completes. If
           an error occurs, this function returns an integer error code and the function pointed
           to by the register_callback parameter will not be called.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_register_job_request_with_info (const char * resource_manager_contact,
       const char * description, int job_state_mask, const char * callback_contact,
       globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t callback, void *
       callback_arg)
       Send a job request to a GRAM service with extensions-aware callback. The
       globus_gram_client_register_job_request_with_info() function sends a GRAM protocol message
       to a service to request that it start a job on behalf of the client.

       If globus_gram_client_register_job_request_with_info() determines that this request could
       not be processed before contacting the gatekeeper (for example, a malformed
       resource_manager_contact), it will return an error, and the callback function will not be
       called. Otherwise, the success or failure an be determined by the operation_failure_code
       parameter to the function pointed to by the callback parameter. The difference between
       this function and globus_gram_client_register_job_request() is the function signature of
       the callback function.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.
           description A pointer to a string containing the job request information formatted in
           RSL syntax.
           job_state_mask A bitwise-or of the GLOBUS_GRAM_PROTOCOL_JOB_STATE_* states that the
           job manager will send job state notification messages for to the contact named by
           callback_contact.
           callback_contact A GRAM listener contact that the job manager will send job state
           notification messages to.
           attr A set of client attributes to use to contact the gatekeeper. If no custom
           attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           callback A pointer to a function to call when the job_request request has completed or
           failed.
           callback_arg A pointer to application-specific data which will be passed to the
           function pointed to by callback as its user_callback_arg parameter.

       Returns
           Upon success, globus_gram_client_register_job_request_with_info() returns
           GLOBUS_SUCCESS and the callback function will be called once the job request operation
           completes. If an error occurs, this function returns an integer error code and the
           function pointed to by the callback parameter will not be called.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

   int globus_gram_client_register_job_signal (const char * job_contact,
       globus_gram_protocol_job_signal_t signal, const char * signal_arg,
       globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback,
       void * register_callback_arg)
       Send a signal a GRAM job. The globus_gram_client_register_job_signal() function sends a
       signal message to a job managed by the GRAM service. Signals consist of a signal number
       and an optional string argument. The meanings of the signals supported by the GRAM job
       manager are defined in the GRAM Protocol documentation. This function returns as soon as
       it has determined that its parameters are valid and it has begun to send the message to
       the GRAM service.

       Parameters
           job_contact The job contact string of the job manager to contact. This is the same
           value returned from globus_gram_client_job_request().
           signal The signal code to send to the job manager.
           signal_arg Parameters for the signal, as described in the documentation for the
           #globus_gram_protocol_job_signal_t enumeration.
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the signal request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, globus_gram_client_job_register_signal() returns GLOBUS_SUCCESS after
           beginning to send the signal to the GRAM job and registers the register_callback
           function to be called once that has completed. If an error occurs, this function
           returns an integer error code indicating why the client could not signal the job.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

       See also
           globus_gram_client_register_job_signal()

   int globus_gram_client_register_job_status (const char * job_contact,
       globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback,
       void * register_callback_arg)
       Send a status query to a GRAM job. The globus_gram_client_register_job_status() function
       initiates a query of the current status of the job associated with the job contact
       parameter. The job's status and failure code are passed to the function pointed to by the
       register_callback parameter. This function returns as soon as it has begun requesting the
       job status.

       Parameters
           job_contact The job contact string of the job to query. This is the same value
           returned from globus_gram_client_job_request().
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the status request has
           completed or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, the globus_gram_client_register_job_status() function returns
           GLOBUS_SUCCESS and begins to send a job state query to the job named by job_contact
           and registers the function pointed to by the register_callback parameter to be called
           once the status query terminates or fails. If an error occurs,
           globus_gram_client_register_job_status() returns an integer error code.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter

   int globus_gram_client_register_job_status_with_info (const char * job_contact,
       globus_gram_client_attr_t attr, globus_gram_client_info_callback_func_t info_callback,
       void * callback_arg)
       Send a status query to a GRAM job. The globus_gram_client_register_job_status_with_info()
       function initiates a query of the current status of the job associated with the job
       contact parameter. Job information is returned via the job_info parameter passed to the
       function pointed to by the info_callback parameter. This function returns as soon as it
       has begun requesting the job status.

       Parameters
           job_contact The job contact string of the job to query. This is the same value
           returned from globus_gram_client_job_request().
           attr A set of client attributes to use to contact the job. If no custom attributes are
           needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           info_callback A pointer to a function to call when the status request has completed or
           failed.
           callback_arg A pointer to application-specific data which will be passed to the
           function pointed to by info_callback as its user_callback_arg parameter.

       Returns
           Upon success, the globus_gram_client_register_job_status_with_info() function returns
           GLOBUS_SUCCESS and begins to send a job state query to the job named by job_contact
           and registers the function pointed to by the info_callback parameter to be called once
           the status query terminates or fails. If an error occurs,
           globus_gram_client_register_job_status_with_info() returns an integer error code.

       Return values
           GLOBUS_GRAM_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources
           GLOBUS_GRAM_PROTOCOL_ERROR_NULL_PARAMETER Null parameter

   int globus_gram_client_register_ping (const char * resource_manager_contact,
       globus_gram_client_attr_t attr, globus_gram_client_nonblocking_func_t register_callback,
       void * register_callback_arg)
       Send a ping request to a GRAM service. The globus_gram_client_register_ping() function
       sends a specially-formatted GRAM protocol message which checks to see if a Gatekeeper is
       running on a given PORT, and whether that Gatekeeper is configured to support the desired
       job manager service. This is used for diagnostic purposes.

       If globus_gram_client_register_ping() determines that this request could not be processed
       before contacting the gatekeeper (for example, a malformed resource_manager_contact), it
       will return an error, and the regiser_callback function will not be called. Otherwise, the
       success or failure an be determined by the operation_failure_code parameter to the
       function pointed to by the register_callback parameter.

       Parameters
           resource_manager_contact A NULL-terminated character string containing a GRAM contact
           that this function will contact.
           attr A set of client attributes to use to contact the gatekeeper. If no custom
           attributes are needed, the caller should pass the value GLOBUS_GRAM_CLIENT_NO_ATTR.
           register_callback A pointer to a function to call when the ping request has completed
           or failed.
           register_callback_arg A pointer to application-specific data which will be passed to
           the function pointed to by register_callback as its user_callback_arg parameter.

       Returns
           Upon success, globus_gram_client_register_ping() returns GLOBUS_SUCCESS and the
           register_callback function will be called once the ping operation completes. If an
           error occurs, this function returns an integer error code and the function pointed to
           by the register_callback parameter will not be called.

       Return values
           GLOBUS_SUCCESS Success
           GLOBUS_GRAM_PROTOCOL_ERROR_MALLOC_FAILED Out of memory
           GLOBUS_GRAM_PROTOCOL_ERROR_PROTOCOL_FAILED Protocol error
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_JOB_CONTACT Invalid job contact
           GLOBUS_GRAM_PROTOCOL_ERROR_INVALID_REQUEST Invalid request
           GLOBUS_GRAM_PROTOCOL_ERROR_NO_RESOURCES No resources

Author

       Generated automatically by Doxygen for globus_gram_client from the source code.