gd_archive

Stores a file or variable with some metadata into the archive.

Syntax

ID = gd_archive(filename)

ID = gd_archive(filename,metadata)

ID = gd_archive(filename,metadata,datagroupID)

ID = gd_archive(v)

ID = gd_archive(v,metadata)

ID = gd_archive(v,metadata,datagroupID)

ID = gd_archive(v,metadata,datagroupID,'var')

Description

ID = gd_archive(filename) takes a string representing a filename and archives that file in a file store (specified in the ClientConfig.xml file). Some standard information about the file (metadata) is automatically generated and can be later queried with gd_query. A unique identifier (ID) for the archived file is returned which can be used to retrieve the file with gd_retrieve.

ID = gd_archive(filename,metadata) archives a file with some user defined metadata which can later be queried with gd_query. Standard metadata about the file is also generated.

ID = gd_archive(filename,metadata,datagroupID) archives a file and adds it to a datagroup specified by datagroupID. A datagroup is used to group together a collection of related files, variables and other datagroups, see gd_datagroup and gd_datagroupadd. To specify a datagroupID without including user defined file metadata, set metadata to empty [].

ID = gd_archive(v) takes a variable and archives it in a database (accessible via the webservices specified in the ClientConfig.xml file). v can be of type char, double, complex, struct, sparse, cell array, or logical. Some standard metadata about the variable is generated automatically and can be later queried with gd_query. A unique identifier (ID) for the archived variable is returned which can be used to retrieve the variable to the workspace with gd_retrieve. A variable can also be assigned user defined metadata and added to a datagroup by supplying a datagroupID in the same way as a file.

ID = gd_archive(v,metadata,datagroupID,'var') should be used when archiving a variable that is a string (char). If v has any other type it will be automatically detected, but when it is a string ‘var’ must be specified to indicate it is a variable and not a filename. If there is no user defined metadata or datagroupID, set them to empty [].

Input Arguments

metadata The metadata structure can contain any combination of named variables, matrices and substructures (char, double, complex, struct, sparse, cell or logical) necessary to describe the data. However, there are two special substructures, standard and access, which may only contain certain values.

Some metadata is automatically generated (even when no metadata is passed to the function) and stored in the standard substructure ofmetadata. For files and variables this consists of ID, userID and archiveDate, and for files only: byteSize, format, localName (the original name of the file) and createDate (when the original file was created/modified). Optional comment, version and tree fields can be added to standard and overriding values for standard.localName and standard.format can also be specified. The tree field is a string which can be used to represent a user defined hierarchy for the data, similar to a directory path, e.g. 'myuserID/designs/testmodel'. See gd_query for further information on these fields. Any other fields set in the standard substructure will be overwritten or removed.

The access substructure of metadata controls who may query and retrieve the data. The person who archived the data automatically has access to it and does not need to be added. access can contain two fields, each of which can be a single string or a cell array of strings:

users	User ID strings specifying which users may access the data.
groups	Group ID strings specifying which groups of users may access the data (currently a group must be created in the database by an administrator).

Examples

Archive a file with no user defined metadata.

ID = gd_archive ('C:\file.dat')

ID =

file_dat_ce868f40-8de0-445e-8ae5-36c05eec25a9

Archive a file with some metadata, m (user defined metadata and a standard comment), and give access permission to user1 and user2.

m.model.name = 'test_design';

m.params = [1 4.7 5.3];

m.iterations = 9000;

m.standard.comment = 'Comment about file';

m.access.users = {'user1','user2'};

gd_archive('C:\file.dat',m);

Archive a file and add it to a datagroup, using [] to indicate no user defined metadata.

datagroupID = gd_datagroup('design opt 2004-09-03');

gd_archive('C:\file.dat',[],datagroupID);

Archive a structure with some user defined metadata.

v.width = 12;

v.height = 6;

m.standard.comment = 'measurement variables';

gd_archive(v,m);

Notes

A valid proxy certificate is required to archive a file or variable (see gd_createproxy from the Geodise Compute Toolbox).