Aliases
A feature that HEC-DSS version 7 provides is alias pathnames. A DSS alias is a pathname that points to a record with a different pathname. The pathname for that record is called the primary pathname. Any operation using an alias pathname is the same as doing the operation on the record with the primary pathname. If you read or write using an alias, you are reading or writing the primary record.
You can have as many aliases for a record as desired. Alias pathnames are not "deleted", but "removed", as a delete would delete the primary record and all aliases, whereas a remove just removes the alias pathname. You cannot rename an alias, but you can remove it and then add another alias with the new name. You also cannot add an alias if that alias already exsits.
Aliases operate on the record level. If you wanted an alias for a dataset with more than one record, such as a year of hourly flows, you can use the condensed reference class to obtain all the pathnames in a dataset, then create aliases for each of those pathnames.
The list of alias functions follows:
- int zaliasAdd(long long ifltab, const char primayPathname, const char* aliasPathname);
- int zaliasGetPrimary(long long ifltab, const char aliasPathname, char* primayPathname, size_t maxLenPrimayPathname);
- int zaliasList(long long ifltab, const char pathname, char** pathameList, int *pathnameListLength);
- int zaliasNumber(long long ifltab, const char pathname);
- int zaliasRemove(long long ifltab, const char aliasPathname);
- int zaliasRemoveAll(long long ifltab, const char pathname);
Note:
int delete(String pathname) // Will delete data and all aliases
Except for zaliasNumber, these functions return STATUS_OKAY (0) for a successful operation, or STATUS_RECORD_NOT_FOUND if the primary pathname does not exist, or a status of less than -1 if an error occurred (see the section on error processing for more information.) In the above functions "pathname" may be either the primary pathname or an alias pathname.
See the following example for use of these functions.
Example: Aliases
#include <stdio.h>
#include <string.h>
#include "heclib.h"
// An example of using aliases
// Assumes that sample7.dss contains the data from sample.dss
int ExampleAlias()
{
long long ifltab[250];
int version;
int status;
char *dssFilename;
char *primaryPathname;
char *aliasPathname;
char *path;
char* pathnameList;
int pathnameListLength;
int count;
// Open the DSS file; It must exist and be the sample.dss file
dssFilename = mallocAndCopy("C:/temp/Sample7.dss");
version = zgetFileVersion(dssFilename);
if (version != 7) {
printf("Error, %s must exist and be a version 7 file\n", dssFilename);
return -1;
}
status = zopen(ifltab, dssFilename);
if (status != STATUS_OKAY) return status;
primaryPathname = mallocAndCopyPath("/AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/OBS/");
// Be sure it exists
status = zcheck(ifltab, primaryPathname);
if (status != STATUS_OKAY) {
printf("Error, primay pathname does not exist, or error. Error code %d\n", status);
return status;
}
// Add an alias to this path
aliasPathname = mallocAndCopyPath("/AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/");
status = zaliasAdd(ifltab, primaryPathname, aliasPathname);
if (status != STATUS_OKAY) return status;
printf("Added alias %s\n", aliasPathname);
// Check
status = zcheck(ifltab, aliasPathname);
if (status != STATUS_OKAY) {
printf("Error, primay aliasPathname does not exist, or error. Error code %d\n", status);
return status;
}
else {
printf("Alias pathanme exists: %s\n", aliasPathname);
}
// Add a second - doesn't matter if you link it to primary or to alias
path = mallocAndCopyPath("/AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias 2/");
status = zaliasAdd(ifltab, aliasPathname, path);
if (status != STATUS_OKAY) return status;
printf("Added alias %s\n", path);
// Check
status = zcheck(ifltab, path);
if (status != STATUS_OKAY) {
printf("Error, primay aliasPathname does not exist, or error. Error code %d\n", status);
return status;
}
else {
printf("Alias pathanme exists: %s\n", path);
}
// Get a list of the aliases that are linked to the primary.
// Since an alias points to the primary, you can use either an alias or primary
status = zaliasList(ifltab, aliasPathname, &pathnameList, &pathnameListLength);
// First one in the list is always primary
printf("\nAlias List:\nPrimary: %s\n", pathnameList);
count = (int)strlen(pathnameList) + 1;
while (count <pathnameListLength) {
printf("Alias: %s\n", &pathnameList[count]);
count += (int)strlen(&pathnameList[count]) + 1;
}
free(pathnameList);
printf("\n");
// Remove an alias - don't delete! Delete will remove both aliases, primary and data
status = zaliasRemove(ifltab, aliasPathname);
if (status != STATUS_OKAY) return status;
// Check
status = zcheck(ifltab, aliasPathname);
if (status == STATUS_RECORD_NOT_FOUND) {
printf("Alias pathname no longer exists : %s\n", aliasPathname);
}
free(dssFilename);
free(primaryPathname);
free(aliasPathname);
zclose(ifltab);
printf("\nCompleted aliases example\n");
return 0;
}10:47:40.881 -----DSS---zaliasAdd: Primary Pathname: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/OBS/
10:47:40.881 Alias Pathname: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
Added alias /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
Alias pathanme exists: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
10:47:40.882 -----DSS---zaliasAdd: Primary Pathname: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
10:47:40.882 Alias Pathname: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias 2/
Added alias /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias 2/
Alias pathanme exists: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias 2/
Alias List:
Primary: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/OBS/
Alias: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias 2/
Alias: /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
Alias pathname no longer exists : /AMERICAN/FOLSOM/FLOW-RES IN/01Jan2006/1Day/Alias Testing/
10:47:40.882 -----DSS---zclose Handle 3; Process: 19360; File: C:\temp\Sample7.dss
10:47:40.883 Number records: 600
10:47:40.883 File size: 182465 64-bit words
10:47:40.883 File size: 1425 Kb; 1 Mb
10:47:40.883 Dead space: 15
10:47:40.883 Hash range: 4096
10:47:40.883 Number hash used: 578
10:47:40.883 Max paths for hash: 2
10:47:40.883 Corresponding hash: 43
10:47:40.883 Number non unique hash: 0
10:47:40.883 Number bins used: 578
10:47:40.884 Number overflow bins: 0
10:47:40.884 Number physical reads: 60
10:47:40.884 Number physical writes: 21
10:47:40.884 Number denied locks: 0
Completed aliases example