gd_archive

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

Syntax

ID = gd_archive(filename,metadata=None,datagroupID='')

ID = gd_archive(v,metadata=None,

datagroupID='',datatype='')

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, use a keyword argument for datagroupID, e.g. gd_archive(myfilename, datagroupID=mydatagroupID).

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 string, integer, float, complex, dictionary, list, or tuple. 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. 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, use a keyword argument for datatype, e.g. gd_archive(v,datatype='var').

Input Arguments

metadata The keys (referred to as fields) in the metadata dictionary must be strings but the values can contain any combination of variables (string, integer, float, complex, dictionary, list, or tuple) necessary to describe the data. There are two special subdictionaries, 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 subdictionary of the metadata dictionary. 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 localName and format can also be specified. The tree value 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 standard fields. Any other fields set in the standard subdictionary will be overwritten or removed.

The access subdictionary 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 list 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.

from gddatabase import *

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

print 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, with no user defined metadata.

dID = gd_datagroup('design opt 2004-09-03')

gd_archive('C:/file.dat',datagroupID=dID)

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).