Client functionality specific to the client-side of DC-API. This section describes the functions and definitions available for DC-API applications on the client side. File types for the DC_resolveFileName() function. Some grid infrastructures use different locations for storing files of different usage, therefore DC-API needs to know the expected usage of logical files to be able to determine the correct physical location. @DC_FILE_IN: the file is an input file. @DC_FILE_OUT: the file is an output file. @DC_FILE_TMP: the file is a temporary file that will not sent back to the master. Logical name of the application-level checkpoint file. See DC_resolveFileName() for details about checkpoint file usage. ClientEvent types that can be received. @DC_CLIENT_CHECKPOINT: a checkpoint should be made. The application must call DC_checkpointMade() to acknowledge the request even if it does not support checkpointing (it should pass a %NULL pointer as the file name in this case). @DC_CLIENT_FINISH: the computation should be aborted. @DC_CLIENT_MESSAGE: a message has arrived. ClientEvent received from the master. @type: type of the event. @message: contents of the message if @type is %DC_CLIENT_MESSAGE. Initializes the client API. This function must be called first before calling any other DC-API functions. @void: @Returns: 0 if successful or a #DC_ErrorCode. Resolves the local name of input/output files. The real name (and path) of an input/output file may be different from what the client expects. This function performs the translation from the logical names used by the client to the real names used by the infrastructure. The client must not assume that it can read/write/create any files other than the names returned by this function. The handling of application-level checkpoint files is special. The intention is to never modify an already completed checkpoint file, so even if the client is interrupted in the middle of writing to the checkpoint file, the previous checkpoint is still intact and can be used to resume computation. When @logicalFileName is %DC_CHECKPOINT_FILE, @type is interpreted as follows: If @type is %DC_FILE_IN, then the path name of the last completed checkpoint file (as indicated by the client by calling DC_checkpointMade() previously) is returned. The client must not modify this file in any way. If the client did not create any checkpoints so far but it was resumed from a previous checkpoint, then the path name of the original checkpoint file is returned. If there are no previous checkpoints at all, %NULL is returned. If @type is %DC_FILE_OUT, then a name for a new non-existant checkpoint file is returned. The client should write the checkpoint information to this file and should call DC_checkpointMade() with this file name to indicate that the checkpoint is complete. After calling DC_checkpointMade(), the client is not allowed to modify the checkpoint file in any way, and must call DC_resolveFileName() again to obtain a new name for a new checkpoint file. When @logicalFileName is not %DC_CHECKPOINT_FILE, the following rules apply: If @type is %DC_FILE_IN, then @logicalFileName must be one of the names the master registered using DC_addWUInput() when the work unit was created. If @type is %DC_FILE_OUT, then @logicalFileName must be one of the names the master registered using DC_addWUOutput() when the work unit was created. If @type is %DC_FILE_TMP, then @logicalFileName must not match any registered input or output logical names. @type: the tpe of the file. @logicalFileName: the logical name of the file used by the client. @Returns: the real path name of the file. The value should be deallocated using free() when it is no longer needed. %NULL is returned if @type is invalid or @logicalFileName is not known to the infrastructure. Sends a sub-result file back to the master. The sending of the file may happen asynchronously, in this case this function will not wait for the transfer to finish (or even to start). @logicalFileName: the logical name of the file to send. This identifier will be received by the master. @path: the local path name of the file to send. @fileMode: tells how the file should be handled. @Returns: 0 if successful or a #DC_ErrorCode. Sends a message to the master. The sending of the message may happen asynchronously, in this case this function will not wait for the transfer to finish (or even to start). The maximum length of a message that may be sent using this function can be determined by calling DC_getMaxMessageSize(). @message: the message to send. @Returns: 0 if successful or a #DC_ErrorCode. Checks for client control events. The returned event should be destroyed using DC_destroyClientEvent() when it is no longer needed. If the returned event is %DC_CLIENT_CHECKPOINT but the client does not support checkpointing, it should still call the DC_checkpointMade() function with a %NULL argument to inform the grid infrastructure that no checkpoint will be delivered. @void: @Returns: a #DC_ClientEvent or %NULL if there are no outstanding events. Destroys an event returned by DC_checkClientEvent(). @event: the event to destroy. Informs the DC-API that an application-level checkpoint has been made. See the DC_resolveFileName() for a description of checkpoint file handling. @fileName: the name of the checkpoint file. This should be a value returned by DC_resolveFileName(%DC_FILE_OUT, %DC_CHECKPOINT_FILE). The checkpoint file must not be modified after this function has been called. @fileName can also be %NULL meaning that the application does not in fact support checkpointing, but just acknowledges a %DC_CLIENT_CHECKPOINT event. Informs the controlling environment about the fraction of the work already done. Ideally this should be the CPU time used so far divided by the total CPU time that will be needed for the computation. @fraction: the fraction of the work completed. Finishes computation. Tells the DC-API to finish this work unit and start a new one. All output files are transferred to the master and the master is notified about the completion of the work unit. @exitcode: the return code of the process that will be reported back to the master. 0 means success; any other value tells the grid infrastructure that the work unit has failed.