Common

Common — functionality available on both the client and master side.

Synopsis

#include <dc_common.h>

enum                DC_ErrorCode;
enum                DC_GridCapabilities;
typedef             DC_FileMode;
#define             DC_CONFIG_FILE
#define             DC_LABEL_STDOUT
#define             DC_LABEL_STDERR
#define             DC_LABEL_CLIENTLOG
                    DC_PhysicalFile;
                    DC_RemoteFile;
char *              DC_getCfgStr                        (const char *name);
int                 DC_getCfgInt                        (const char *name,
                                                         int defaultValue);
int                 DC_getCfgBool                       (const char *name,
                                                         int defaultValue);
void                DC_log                              (int level,
                                                         const char *fmt,
                                                         ...);
void                DC_vlog                             (int level,
                                                         const char *fmt,
                                                         va_list args);

int                 DC_getMaxMessageSize                (void);
int                 DC_getMaxSubresults                 (void);
unsigned            DC_getGridCapabilities              (void);

Description

The functions and definitions described below are available at both the client and master side of DC-API in the same form, but may have a slightly different meaning.

Details

enum DC_ErrorCode

typedef enum {
	DC_OK,			/* No error */
	DC_ERR_CONFIG,		/* Configuration error */
	DC_ERR_DATABASE, /* Error with the internal data base */
	DC_ERR_NOTIMPL,		/* Not implemented by the API or by the
				   underlying grid infrastructure */
	DC_ERR_UNKNOWN_WU, /* Unknown WU identifier */
	DC_ERR_TIMEOUT,		/* Timeout */
	DC_ERR_BADPARAM, /* Bad function parameter */
	DC_ERR_SYSTEM,		/* A system call has failed, check errno */
	DC_ERR_INTERNAL, /* Internal error */
} DC_ErrorCode;

Error codes returned by DC-API functions.

DC_OK

no error.

DC_ERR_CONFIG

configuration error (syntax error, illegal or missing values).

DC_ERR_DATABASE

database error.

DC_ERR_NOTIMPL

the function is not implemented.

DC_ERR_UNKNOWN_WU

the work unit is not known to DC-API.

DC_ERR_TIMEOUT

the operation timed out.

DC_ERR_BADPARAM

the function was passed illegal parameters.

DC_ERR_SYSTEM

a system call has failed, check errno for the reason.

DC_ERR_INTERNAL

an internal error occured in DC-API.

enum DC_GridCapabilities

typedef enum {
	DC_GC_EXITCODE		= (1 << 0), /* DC_Result contains the
						   client's exit code */
	DC_GC_STDOUT		= (1 << 1), /* The client's standard output
						   is available for the
						   master */
	DC_GC_STDERR		= (1 << 2), /* Client's standard error is
						   available for the master */
	DC_GC_LOG		= (1 << 3), /* Log file generated by the
						   execution environment is
						   available for the master */
	DC_GC_SUSPEND		= (1 << 4), /* DC_suspendWU() works */
	DC_GC_SUBRESULT		= (1 << 5), /* Sub-results work */
	DC_GC_MESSAGING		= (1 << 6) /* Message sending works */
} DC_GridCapabilities;

These flags define the capabilities of the underlying grid system.

DC_GC_EXITCODE

the client's exit code is propagated to the master.

DC_GC_STDOUT

the client's standard output is sent back to the master.

DC_GC_STDERR

the client's standard error is sent back to the master.

DC_GC_LOG

infrastructure-specific log files are available.

DC_GC_SUSPEND

suspending of work units is supported.

DC_GC_SUBRESULT

subresults are supported.

DC_GC_MESSAGING

message sending is supported.

DC_FileMode

typedef int DC_FileMode;

Tells how should DC-API treat physical files passed to it.


DC_CONFIG_FILE

#define DC_CONFIG_FILE		"dc-api.conf"

Default name of the DC-API configuration file.


DC_LABEL_STDOUT

#define DC_LABEL_STDOUT		"dc_stdout.txt"

Logical name of the client's standard output used with DC_getResultOutput().


DC_LABEL_STDERR

#define DC_LABEL_STDERR		"dc_stderr.txt"

Logical name of the client's standard error used with DC_getResultOutput().


DC_LABEL_CLIENTLOG

#define DC_LABEL_CLIENTLOG "dc_clientlog.txt"

Logical name of the client's ifrastructure log used with DC_getResultOutput().


DC_PhysicalFile

typedef struct {
	char			*label;
	char			*path;
	DC_FileMode		mode;
	char			*physicalfilename;
	char			*physicalfilehash;
    int             persistentonclient;
} DC_PhysicalFile;

Describes a physical file.

char *label;

logical name of the file as used by the application.

char *path;

the real path name of the file.

DC_FileMode mode;

usage mode of the file.

char *physicalfilename;

filename to be used in case of Attic files.

char *physicalfilehash;

MD5 hash and size information of Attic files.

int persistentonclient;


DC_RemoteFile

typedef struct {
	char			*label;
	char			*url;
	char			*remotefilehash;
	size_t			remotefilesize;
    int             persistentonclient;
} DC_RemoteFile;

Describes a physical file.

char *label;

logical name of the file as used by the application.

char *url;

the URL of the file.

char *remotefilehash;

the MD5 hash of the file.

size_t remotefilesize;

the size of the file.

int persistentonclient;


DC_getCfgStr ()

char *              DC_getCfgStr                        (const char *name);

Returns the value belonging to the specified key name in the configuration file.

name :

the key to look up.

Returns :

the value belonging to the key or NULL if it is not defined in the config file. The returned value must be deallocated using free() when it is no longer needed.

DC_getCfgInt ()

int                 DC_getCfgInt                        (const char *name,
                                                         int defaultValue);

Returns the integer value belonging to the specified key name in the configuration file. Unit suffixes like 'KB', 'GB' or 'hour' are also allowed.

name :

the key to look up.

defaultValue :

the default value to return if the key is not defined or its value cannot be interpreted as a number.

Returns :

the value belonging to the key or defaultValue if it is not defined in the config file.

DC_getCfgBool ()

int                 DC_getCfgBool                       (const char *name,
                                                         int defaultValue);

Returns the boolean value belonging to the specified key name in the configuration file.

name :

the key to look up.

defaultValue :

the default value to return if the key is not defined or its value cannot be interpreted as a boolean value.

Returns :

the value belonging to the key or defaultValue if it is not defined in the config file.

DC_log ()

void                DC_log                              (int level,
                                                         const char *fmt,
                                                         ...);

Emits a message to the master's log file.

level :

the severity of the. The level codes defined for the system's syslog() function should be used.

fmt :

format of the message, as per printf().

... :

any extra arguments required by fmt.

DC_vlog ()

void                DC_vlog                             (int level,
                                                         const char *fmt,
                                                         va_list args);

Emits a message to the master's log file.

level :

the severity of the. The level codes defined for the system's syslog() function should be used.

fmt :

format of the message, as per printf().

args :

any extra arguments required by fmt.

DC_getMaxMessageSize ()

int                 DC_getMaxMessageSize                (void);

Returns the maximum length of a message that DC_sendMessage() (client side) and DC_sendWUMessage() (master side) accepts.

Returns :

the maximum allowed message size.

DC_getMaxSubresults ()

int                 DC_getMaxSubresults                 (void);

On the master side, returns the maximum number of sub-result files that can be specified when creating a new work unit.

On the client side, returns the number of sub-results the client is still allowed to send.

Returns :

the number of sub-results allowed.

DC_getGridCapabilities ()

unsigned            DC_getGridCapabilities              (void);

Determines the capabilities of the underlying grid infrastructure.

Returns :

the appropriate DC_GridCapabilities constants OR'ed together.