Request an information service from a server
unsigned int dic_info_service (name, type, timeout, address, size, user_routine, tag, fill_address, fill_size)
char *name;
Service name, same name used by server when declaring the service.int type;
Type of service, constants defined are: ONCE_ONLY, TIMED or MONITORED:
ONCE_ONLY: The client will receive the data once and disconnect from the server.
TIMED: The client will receive the data at regular intervals, specified by the parameter timeout. In principle to be used with servers that do not explicitly update the service (using dis_update_service()).
MONITORED: The client will receive the data when the server updates it (by calling dis_update_service()), but also at regular intervals if the "timeout" parameter is different from 0. The "timeout" parameter can be set to 0 to receive data only on server update.int timeout;
For a TIMED or MONITORED service "timeout" indicates the time interval the server should use to send new data, for ONCE_ONLY services it indicates the time after which the service is considered to have failed.int *address;
Address of the buffer where to store the data when the service returns from the server. This parameter can be set to 0 and only the callback routine will be executed.int size;
The size in bytes of the previous buffer (if specified).void *user_routine;
The address of a routine to be executed when new data is returned from the server, the parameters of this routine will be specified later in this document. Can be set to 0 if no callback routine is necessary.long tag;
A parameter to be sent to the user_routine in order to identify the service that has completed.int *fill_address;
Address of a buffer containing data to be stored in the service buffer or passed to the callback routine in case the service doesn't succeed.int fill_size;
The size in bytes of the previous buffer.
unsigned int service_id;
The service identifier, to be used when (if) releasing the service.
This routine first contacts the name server in order to get the address of the server where the requested service is available, and then sends the request directly to the server. When the service arrives from the server the client buffer is filled with the data and/or the user_routine is executed.After a timeout (timeout parameter for ONCE_ONLY services and 2*timeout parameter for TIMED or MONITORED services) the service is considered failed, the information in fill_address is copied into the client buffer and/or the user_routine is called.
If the server is not responding the client recontacts the name server and the name server will wake up the client as soon as the server is up.
Request a time stamped (and quality flagged) information service from a server
unsigned int dic_info_service_stamped (name, type, timeout, address, size, user_routine, tag, fill_address, fill_size)
char *name;
Service name, same name used by server when declaring the service.int type;
Type of service, constants defined are: ONCE_ONLY, TIMED or MONITORED:
ONCE_ONLY: The client will receive the data once and disconnect from the server.
TIMED: The client will receive the data at regular intervals, specified by the parameter timeout. In principle to be used with servers that do not explicitly update the service (using dis_update_service()).
MONITORED: The client will receive the data when the server updates it (by calling dis_update_service()), but also at regular intervals if the "timeout" parameter is different from 0. The "timeout" parameter can be set to 0 to receive data only on server update.int timeout;
For a TIMED or MONITORED service "timeout" indicates the time interval the server should use to send new data, for ONCE_ONLY services it indicates the time after which the service is considered to have failed.int *address;
Address of the buffer where to store the data when the service returns from the server. This parameter can be set to 0 and only the callback routine will be executed.int size;
The size in bytes of the previous buffer (if specified).void *user_routine;
The address of a routine to be executed when new data is returned from the server, the parameters of this routine will be specified later in this document. Can be set to 0 if no callback routine is necessary.long tag;
A parameter to be sent to the user_routine in order to identify the service that has completed.int *fill_address;
Address of a buffer containing data to be stored in the service buffer or passed to the callback routine in case the service doesn't succeed.int fill_size;
The size in bytes of the previous buffer.
unsigned int service_id;
The service identifier, to be used when (if) releasing the service.
This routine first contacts the name server in order to get the address of the server where the requested service is available, and then sends the request directly to the server. When the service arrives from the server the client buffer is filled with the data and/or the user_routine is executed.After a timeout (timeout parameter for ONCE_ONLY services and 2*timeout parameter for TIMED or MONITORED services) the service is considered failed, the information in fill_address is copied into the client buffer and/or the user_routine is called.
If the server is not responding the client recontacts the name server and the name server will wake up the client as soon as the server is up.
In contrast to dic_info_service(), this routine enables the client to obtain a quality flag and a time stamp together with the data.
Have a look at dic_get_quality() and dic_get_timestamp() below.
Gets the quality of a received service.
int dic_get_quality (service_id);
unsigned int service_id;
The service_id returned by dic_info_service_stamped(), or 0 for the"current" service.
int quality;
A flag for the quality of a service.
This routine can be called by a DIM client to obtain the quality flag of a service.
Normally this function should be called inside the client callback function, in which case the service_id can be 0 (meaning the current service).If a DIM client subscribes to a service using the routine dic_info_service_stamped(), the DIM server will publish the quality flag together with the updated service data.
Gets the time stamp of a received service.
int dic_get_timestamp (service_id, secs, milisecs)
unsigned int service_id;
The service_id returned by dic_info_service_stamped(), or 0 for the"current" service.
int *secs;
Time in seconds since January 1, 1970.
int *milisecs;
Time in milliseconds (a value between 0 and 999).
int return_code;
Returns1 if the request was successful.
This routine can be called by a DIM client to obtain the time stamp of a service.
Normally this function should be called inside the client callback function, in which case the service_id can be 0 (meaning the current service).If a DIM client subscribes to a service using the routine dic_info_service_stamped(), the DIM server will publish the time stamp together with the updated service data.
Gets the format description of a received service.
char *dic_get_format (service_id)
unsigned int service_id;
The service_id returned by dic_info_service(), or 0 for the"current" service.
char *description;
A description string containing the data type of a service. A service can be described in this form.
This routine can be called by a DIM client to obtain the description string of a service published by a server. The description string can be used to obtain the data type of a service.
Normally this function should be called inside the client callback function, in which case the service_id can be 0 (meaning the current service).
Called by a client when a service is not needed anymore.
void dic_release_service (service_id)
unsigned service_id;
The service_id returned by dic_info service().
This routine tells the server not to update this service anymore and destroys all the references to it in the client.
Request the execution of a command by a server.
int dic_cmnd_service (name, address, size)
char *name;
Service name, same name used by server when declaring the command service.int *address;
Address of the buffer containing the command data.int size;
The size in bytes of the previous buffer.
int return_code;
Returns1 if the command was successfully requested.
This routine requests the execution of a command by a server, address and size contain the command parameters. This implies contacting the name server (if the command in not know already) and then contacting directly the server. This routine does not report back the completion of the command since these operations are only scheduled and may complete asynchronously.If the server is not responding the command is discarded (in order to avoid having it sent later when it might not be desired anymore).
This routine allows clients (user interfaces for ex.) to send commands to be executed by the servers.
Request the execution of a command by a server and registers a completion callback
int dic_cmnd_callback (name, address, size, cmd_callback, tag )
char *name;
Service name, same name used by server when declaring the command service.int *address;
Address of the buffer containing the command data.int size;
The size in bytes of the previous buffer.void *cmd_callback;
The address of a routine to be executed when the command completes, in order to report the success or failure of the operation. The parameters of this routine will be specified later in this document.long tag;
A parameter to be sent to the cmd_callback in order to identify the command that has completed.
int return_code;
Returns1 if the command was successfully requested.
This routine requests the execution of a command by a server, address and size contain the command parameters. This implies contacting the name server (if the command in not know already) and then contacting directly the server. This routine does not report back the completion of the command since these operations are only scheduled and may complete asynchronously. The cmd_callback routine will be executed on completion.If the server is not responding the command is discarded (in order to avoid having it sent later when it might not be desired anymore).
This routine allows clients (user interfaces for ex.) to send commands to be executed by the servers
Disable padding of received services.
void void dic_disable_padding()
void;
When _not_ to use this routine: If you want to map the data of a received service to a pre-declared structure, DIM will do the "padding" of the data to match the structure as required by the platform where it is running. (for example if a char is followed by an int in the structure DIM will add three dummy bytes between the two).
When to use this routine: If you like to advance a pointer over a received buffer and cast the data by yourself, then padding should be disabled.
If padding should be disabled, this routine has to be called at the beginning of a program (before any other DIM calls).
Gets the process identification of this DIM client.
int dic_get_id (name)
char *name;
Process ID of the DIM client process. The format of the process ID is "PID@NODENAME".
int success;
Returns 1;
Obtains the process ID of the DIM client in the format "PID@NODENAME".
Set the DNS node name for a DIM client.
int dic_set_dns_node (node_name)
char *node_name
The node (or a list of nodes separated by commas) where the DNS is (possibly) running.
int return_code
Returns 1 if successful.
This routine can be called by a client program before subscribing to any services in order to programmatically declare the node where the DNS is running. If this call is not used the environment variable DIM_DNS_NODE will be used instead.
A list of node names separated by commas can be given as a parameter, in which case the client will use the first name server found running from the list.
Unlike dim_set_dns_node() this function allows using different DIM Name Servers (DNSs) for the client and server part of a process.
Get the DNS node name for a DIM client.
int dic_get_dns_node (node_name)
char *node_name
Returns the node (or a list of nodes separated by commas) where the DNS is (possibly) running.
int return_code
Returns 1 if successful.
This routine can be called by a client program to find out where the DNS was defined to be running.
Set the DNS port number for a DIM client.
int dic_set_dns_port (int port)
int port
The port number of the DNS.
int return_code
Returns 1 if successful.
This routine can be called by a client program before subscribing to any services, together with dic_set_dns_node() in order to programmatically declare the port number used by the DNS (if the DNS was started with a non-default port number by using the environment variable DIM_DNS_PORT). The default port number of the DNS is 2505.
Get the DNS port number for a DIM client.
int dic_get_dns_port ()
int port
Returns the DNS port number.
This routine can be called by a client program to find out what port number was defined for the DNS.
Add an error handler to this client.
void dic_add_error_handler (error_user_routine)
void *error_user_routine;
The address of a routine to be executed when the client sees an error.
If no error handler is declared a DIM client will print an error message on the standard output whenever it sees a problem.
If the user declares an error handler the error message and its severity as well as an error code will be passed to the error_user_routine and the user can decide what to do with it.
Routine written by the user, called when new data arrives from a server. The user routine is called with three parameters, please read carefully the parameter description.
void user_routine (tag, buffer, size)
long *tag;
A parameter in order to identify the service, the tag given to dic_info_service. Passed by reference for FORTRAN compatibilityint *buffer;
This parameter contains the address of the data received from the server. If the user has supplied "address" when calling dic_info_service buffer points to "address", otherwise it points to a temporarily allocated buffer where the data received has been stored ( in this case this buffer address is valid only during the execution of this routine, if the data contained in this buffer has to be used later it's the responsibility of the user to copy it to another buffer).int *size;
The size in bytes of the data actually sent by the server. Passed by reference
This routine is called on reception of data from a server, it can be used for ex. by user_interfaces in order to update the screen whith the new set of data.
Routine written by the user, called on command completion. This routine is called with two parameters, please read carefully the parameter description.
void cmd_callback (tag, ret_code)
long *tag;
A parameter in order to identify the command, the tag given to dic_cmd_callback. Passed by reference for FORTRAN compatibilityint *ret_code;
The return code: 1 if the command was successfully sent, i.e., the server was found and the command successfully written out; 0 otherwise. Passed by reference
This routine is called on command completion to check or wait for successful delivery.
Routine written by the user in order to implement an error handler.
void error_user_routine (severity, error_code, message)
int severity;
A severity code: 0 - info, 1 - warning, 2 - error, 3 - fatal.
int error_code;
An error code.
char *message;
The error message explaining the detected error.
This routine should be declared by dic_add_error_handler(). It is called whenever an error is detected by DIM. Normally it should print or store the error as the user finds convenient.
Gets the identification of the current DIM server.
int dic_get_server (char *name)
char *name;
Gets the identification of the current DIM server. The format of the server is "DIMSERVERNAME@NODENAME", where DIMSERVERNAME is the name of theDIM server and NODENAME is the name of the node on which the server is running.
int conn_id;
Returns the server_id, in terms of its connection id, or 0 if no server is currently being handled;
This routine should be called inside the client callback routine when service data is being received from a server.
It obtains the name of the DIM server in the format "DIMSERVERNAME@NODENAME".
Gets the connection ID of the current DIM server.
int dic_get_conn_id ()
int conn_id;
Returns the conn_id of a DIM server
This routine should be called inside the client callback routine when service data is being received from a server. Its purpose is to obtain the conn_id that is required by other routines.
Gets the services of a DIM server to which the client has subscribed.
char *dic_get_server_services (conn_id)
int conn_id;
conn_id of a DIM server as obtained by the routine dic_get_conn_id.
char *services
Returns a list of services of the specified server, to which this client has subscribed.
This routine should be called inside the client callback routine when service data is being received from a server. Its purpose is to get a list of all services, to which this DIM client has subscribed. The list contains only the services of the specified server.
Gets the names of DIM services that have an error.
char *dic_get_error_services ()
char *services;
Returns a list of services, that originated the error.
This routine should be called inside the error_user_routine to find out, which service(s) have an error.