Alias Functions
zaliasGetPrimary
Description: Gets the primary pathname from an alias pathname
Declaration:
int zaliasGetPrimary(long long ifltab, const char aliasPathname, char* primayPathname, size_t maxLenPrimayPathname);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* aliasPathname
The alias pathname. Must be a full unique pathname and follow pathname rules.
char* primayPathname (output)
A character array that will contain the primary pathname on return.
size_t maxLenPrimayPathname
The size of (number of characters) of primayPathname.
Returns:
STATUS_RECORD_FOUND if primary pathname found and not returned. STATUS_RECORD_NOT_FOUND if primary record does not exist
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
See zaliasAdd for a discussion of aliases
zaliasList
Description: Gets a list of aliases associated with a pathname
Declaration:
int zaliasList(long long *ifltab, const char* pathname, char** pathameList, int *pathnameListLength);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* pathname
The seed pathname. May be a primary or alias.
char** pathameList (output)
pointer to a character array that will contain a list of the alias pathnames on return. Memory is malloced, so be sure to free the list upon completion.
int *pathnameListLength
A pointer to an int that will contain the number of characters in the pathnameList.
Returns:
int numberPathnames
The number of pathnames in the list, with the primary the first 0, if no primary
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Discussion:
The pathnameList will contain the primary pathname as the first pathname in the list, followed by aliases, usually in the order of last one added to first added. Each pathname is null terminated.
Example:
char* pathnameList;
int pathnameListLength;
status = zaliasList(ifltab, "/A/B/C/D/E/F/", &pathnameList, &pathnameListLength);
printf("Primary: %s\n", pathnameList);
count = strlen(pathnameList) + 1;
while (count <pathnameListLength) {
printf("Alias: %s\n", &pathnameList[count]);
count += strlen(&pathnameList[count]) + 1;
}
free(pathnameList);
zaliasNumber
Description: Gets the number of aliases associated with a pathname
Declaration:
int zaliasNumber(long long ifltab, const char pathname);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* pathname
The seed pathname. May be a primary or alias.
Returns:
int numberPathnames
The number of pathnames in the list, with the primary the first 0, if no primary
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
zaliasAdd
Description: Adds an alias pathname to a single record.
Declaration:
int zaliasAdd(long long ifltab, const char primayPathname, const char* aliasPathname);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* primayPathname
The pathname of the existing record to alias to. Must be the full unique pathname (not part of a dataset; e.g., correct D part for time series.)
const char* aliasPathname
The alias pathname. Must be a full unique pathname and follow rules (e.g., you cannot change the E or D parts for time series data.)
Returns:
STATUS_OKAY if alias added.
STATUS_RECORD_NOT_FOUND if primary record does not exist.
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Discussion:
An alias is a pathname that (eventualy) points to a record that has a primary name. You may have serveral pathnames aliased to the same recored (although rare). If just one, then the pathname bin of the alias points to the info block of the primary, and the alias address points to the pathname bin of the alias (not the full bin block, just the bin for the individual alias record.) If more than one alias, the the info block points to the last alias bin. That alias bin points to the previous alias bin, which either points to the previous alias bin or to the real info block. You only can tell if it is the real info block or an alias bin by reading that area and examining the status flag (for an alias, this will be 2; the real will be 1)
For serveral alias, you will need to walk the chain down through aliases to find the primary. It is anticipated that aliases will be used infrequently, and that when they are, it will typically be only one. However, this methodology allows for unlimited aliases for a recored.
zaliasRemove
Description: Removes an aliases pathname.
Declaration:
int zaliasRemove(long long ifltab, const char aliasPathname);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* aliasPathname
The alias pathname to remove. Cannot be the primary.
Returns:
STATUS_OKAY if alias added.
STATUS_RECORD_NOT_FOUND if primary record does not exist.
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
This does not delete any data, just the alias pathname. zdelete will delete all aliases and data. see zaliasRemoveAll() to remove all aliases for one pathname.
zaliasRemoveAll
Description: Removes all aliases associated with one primary pathname
Declaration:
int zaliasRemoveAll(long long ifltab, const char pathname);
Parameters:
long long ifltab
The ifltab of the DSS file.
const char* pathname
The seed pathname. May be a primary or alias.
Returns:
int numberPathnames
The number of alias (that were removed), excluding the primary 0, if no aliases.
STATUS_RECORD_NOT_FOUND
< -1. error code - value contains a description of the error and where it occurred. See zerrorDecode for descriptions.
Remarks:
This does not delete any data, just alias pathnames. zdelete will delete alias and data. The logic of removing all is different enough from removing one, that it warrants it own function See zaliasAdd for a discussion of aliases