Common

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

Synopsis


#include <dc_common.h>


enum        DC_ErrorCode;
enum        DC_GridCapabilities;
enum        DC_FileMode;
#define     DC_CONFIG_FILE
#define     DC_LABEL_STDOUT
#define     DC_LABEL_STDERR
#define     DC_LABEL_CLIENTLOG
            DC_PhysicalFile;
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.

enum DC_FileMode

typedef enum {
	DC_FILE_REGULAR,	/* Not persistent, needs copy */
	DC_FILE_PERSISTENT,	/* Persistent, link is enough */
	DC_FILE_VOLATILE	/* DC-API should remove the original */
} DC_FileMode;

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

`DC_FILE_REGULAR`	the application wishes to continue using the file, so DC-API must make an internal copy of it.
`DC_FILE_PERSISTENT`	the application guarantees that the file will not change and will not be deleted during the lifetime of the application. This lets DC-API use symbolic or hard links instead of copying to save space.
`DC_FILE_VOLATILE`	the application does not want to use the file in any way in the future. DC-API will remove the file when it is no longer needed.

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;
} 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.

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.