openfam::fam::fam_restore

restore data from archival storage to a FAM-resident data item .

Synopsis

void *fam_restore(const char *BackupName, Fam_Descriptor *dest);

OR

void *fam_restore(const char *BackupName, Fam_Region_Descriptor *destRegion, const char *dataitemName, mode_t accessPermissions, Fam_Descriptor **dest);

Description

Initiates a restore operation of data from an archival storage to a FAM-resident data item. User can either specify the data item in which the data has to be restored using 1st Option or can request for creation of data item of a given name in a given region, for given set of permissions as in 2nd Option.

Input Arguments

Return Values

Returns a pointer to the wait object for the restore operation. This object can be used to wait for the completion of the restore operation. Throws Fam_Exception on error.

Fam Error Numbers

Notes

Note that the method is non-blocking: it returns after the restore has been initiated, and does not wait for completion of the transfer. Also note that fam_restore() performs an inconsistent restore, in that the restored data may reflect updates that are performed concurrently with the restore operation, rather than a point-in-time snapshot of the destination data item that is consistent as of the beginning of restore operation. If the application desires a consistent restore, it is responsible for coordinating PE activity during the restore operation.

Example

#include <string.h>
#include <fam/fam.h>
#include <fam/fam_exception.h>
using namespace std;
using namespace openfam;
	
int main(void) {
	fam *myFam = new fam();
	
	// ... Initialization code here

	 try {
		// look up the descriptor to a previously allocated (source) data item.
		Fam_Descriptor *descriptor = myFam->fam_lookup("myItem", "myRegion");
		
		// name of restore for given data item.
		char *backupName = (char *)malloc(FILE_MAX_LEN);
		sprintf(backupName, "%s.%s", "myRegion", "myItem");

		// initiates restore APIs and returns a waitObject to restore operation.
		void *waitObj = myFam->fam_restore(backupName, descriptor);
	
		// Wait for restore operation to complete.
		myFam->fam_restore_wait(waitObj);
		printf("restore of data item is successful\n");
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }
	
	 // ... subsequent code here
}

OR

#include <string.h>
#include <fam/fam.h>
#include <fam/fam_exception.h>
using namespace std;
using namespace openfam;
	
int main(void) {
	fam *myFam = new fam();
	perm_t perm = 0777;
	// ... Initialization code here

	 try {
        Fam_Region_Descriptor *desc = myFam->fam_lookup("myRegion");
	 
		// name of restore for given data item.
		char *backupName = (char *)malloc(FILE_MAX_LEN);
		sprintf(backupName, "%s.%s", "myRegion", "myItem");

		// initiates restore APIs and returns a waitObject to restore operation.
		void *waitObj = myFam->fam_restore(backupName, desc, "secondDI", perm,descriptor);
	
		// Wait for restore operation to complete.
		myFam->fam_restore_wait(waitObj);
		printf("restore of data item is successful\n");
	 } catch (Fam_Exception &e) {
		printf("fam API failed: %d: %s\n", e.fam_error(), e.fam_error_msg());
	 }
	
	 // ... subsequent code here
}