MCAT API
From SRB
The following are the API calls that interact with the MCAT.
[edit]
srbGetDatasetInfo
/*
* srbGetDatasetInfo - Get Info on a SRB data object. * * Input : srbConn* conn, * int catType - The catalog type - 0 = MDAS_CATALOG * char *objID, * char *collectionName * mdasC_sql_result_struct *myresult - A pointer to a user supplied * mdasC_sql_result_struct. * int rowsWanted - number of rows of result wanted. * char *mode * Output: * A mdasC_sql_result_struct *myresult * * Return value : * 0 - success; myresult->continuation_index >= 0, ==> more results from * the query. Use srbGetMoreRows() to retrieve more rows. * a negative value - failure */
extern int srbGetDatasetInfo(srbConn* conn, int catType, char *objID, char *collectionName, mdasC_sql_result_struct *myresult, int rowsWanted, char *mode);
[edit]
srbGetDataDirInfo
/*
* srbGetDataDirInfo - A general purpose routine used by clients to query
* the MCAT. The schema of the MCAT is quite complicated containing hundreds
* of tables and attributes. The srbGetDataDirInfo() API provides a simple way
* for clients to query the MCAT without having to know the MCAT schema by
* providing a single table view to the MCAT. From a client standpoint,
* the MCAT contains of a single table with hundreds of attributes. The query
* inputs are the qval[][] and selval[] arrays and the result of the query is
* returned in the myresult struct containing rows of attribute values.
* Both selval[] and qval[][] are arrays of size MAX_DCS_NUM and are indexed
* by values given in src/catalog/include/mdasC_db2_externs.h under the
* heading DCS-ATTRIBUTE-INDEX DEFINES. Each attribute is represented by
* an element in the array. The selval[] array specifies a list of attrbutes
* to select in the query and qval[][] specifies a lists of conditions
* (predicates) in the query. e.g., selval[USER_NAME] = 1 means the
* "user_name" attribute is to be retrieved.
*
* The qval[][] array specifies the "=" predicates to search. e.g.,
* sprintf(qval[DATA_NAME],"'%s'", "unixFileObj1"); means that the search
* condition includes the term (data_name = "unixFileObj1").
*
* An example of srbGetDataDirInfo:
*
* mdasC_sql_result_struct myresult;
* char qval[MAX_DCS_NUM][MAX_TOKEN];
* int selval[MAX_DCS_NUM];
*
* memset (qval, 0, sizeof (qval));
* memset (selval, 0, sizeof (selval));
* sprintf(qval[DATA_NAME],"'%s'",argv[2]);
* selval[PATH_NAME] = 1;
* selval[RSRC_NAME] = 1;
* .
* .
* if (srbGetDataDirInfo(conn, MDAS_CATALOG, qval, selval, &myresult) < 0) {
* fprintf(stderr, "can't srbGetDataDirInfo \n");
* exit_nicely(conn);
* }
*
*
*
* Input : srbConn* conn,
* int catType - The catalog type - 0 = MDAS_CATALOG
* char qval[][MAX_TOKEN] - A point to a user supplied
* char qval[MAX_DCS_NUM][MAX_TOKEN] array.
* int *selval - A pointer to a user supplied selval[MAX_DCS_NUM]
* array.
* int rowsWanted - number of rows of result wanted.
*
* Output:
* A mdasC_sql_result_struct *myresult
*
* Return value :
* 0 - success; myresult->continuation_index >= 0, ==> more results from
* the query. Use srbGetMoreRows() to retrieve more rows.
* a negative value - failure
*/
extern int srbGetDataDirInfo(srbConn* conn, int catType, char qval[][MAX_TOKEN], int *selval, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
srbGetDataDirInfoWithZone
/* This is the same as srbGetDataDirInfo except with an additional
* char *myMcatZone input */
extern int srbGetDataDirInfoWithZone(srbConn* conn, int catType, char *myMcatZone, char qval[][MAX_TOKEN], int *selval, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
srbGenQuery
/*
* srbGenQuery - This is a more compact form of srbGetDataDirInfo. * Instead of using fixed array of selval and qval, it uses the * genQuery struct. * * * Input : srbConn* conn, * int catType - The catalog type - 0 = MDAS_CATALOG * char *myMcatZone - The MCAT zone for this query. Only valid * for version 3.x.x and above. For version 2.x.x, this should be NULL. * genQuery_t *myGenQuery - The input query in th form of genQuery_t * instead of selval and qval of srbGetDataDirInfo. * mdasC_sql_result_struct *myresult - The output query result. * int rowsWanted - number of rows of result wanted. * * Output: * A mdasC_sql_result_struct *myresult * * Return value : * 0 - success; myresult->continuation_index >= 0, ==> more results from * the query. Use srbGetMoreRows() to retrieve more rows. * a negative value - failure * * Note : We cannot use the generic routine clCall() because the input * byte stream is not a char string. */
extern int srbGenQuery (srbConn* conn, int catType, char *myMcatZone, genQuery_t *myGenQuery, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
srbRegisterDataset
/*
* srbRegisterDataset - Register a SRB dataset * * Input - srbConn* conn - From clConnect (). * int catType - catalog type. e,g., MDAS_CATALOG. * char *objID - The SRB object ID to create. The objID is obtained * through registration with MDAS. * char *dataTypeName - Data type. e.g. "generic" * char *resourceName - The storage resource name. * e.g. "mda18-unix-sdsc" * char *collectionName - The collection name. * char *pathName - The file/DB path of the data. * srb_long_t dataSize - The size of the dataset if known. 0 = unknown. * * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbRegisterDataset (srbConn* conn, int catType, char *objID, char *dataTypeName, char *resourceName, char *collectionName, char *pathName, srb_long_t dataSize);
[edit]
srbUnregisterDataset
/*
* srbUnregisterDataset - Unregister an SRB object * * Input - srbConn* conn - From clConnect (). * char *objID - The SRB object ID to unlink. The objID is obtained * through registration with MDAS. * char *collectionName - The name of the collection this objID * belongs. * * Output - Returns 0 upon success. * Returns a negative value upon failure. * */
extern int srbUnregisterDataset (srbConn* conn, char *objID, char *collectionName);
[edit]
srbSetAuditTrail
/*
* srbSetAuditTrail - Setting and Unsetting Audit Trail. * * Input - srbConn* conn - From clConnect (). * int set_value - The Audit Trail value to set. * AUDIT_TRAIL_OFF - turn on audit trail. * AUDIT_TRAIL_ON - turn on audit trail. * GET_AUDIT_TRAIL_SETTING - return the cuurent audit trail * setting without modifying the setting. * * Output - Returns the currently audit trail setting (after processing * the latest change request). */
extern int srbSetAuditTrail (srbConn* conn, int set_value);
[edit]
srbModifyDataset
/*
* srbModifyDataset - Modify a SRB dataset * * Input - srbConn* conn - From clConnect (). * int catType - catalog type. e,g., MDAS_CATALOG. * char *objID - The SRB object ID to modify. The objID must * already have been registered with the MDAS catalog. * char *collectionName - The name of the collection this objID * belongs. * char *resourceName - The storage resource name. * e.g. "mda18-unix-sdsc" * char *pathName - The file/DB path of the data. * * char *dataValue1 - Input value 1. See the prototype for the * modify_dataset_info() function in * catalog/include/mdasPrototypes.h for the definition of * dataValue1, dataValue2 and retractionType. * * char *dataValue2 - Input value 2. * int retractionType - The type of retraction. See srbC_mdas_externs.h * for the retractionType definition. * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbModifyDataset (srbConn* conn, int catType, char *objID, char *collectionName, char *resourceName, char *pathName, char *dataValue1, char *dataValue2, int retractionType);
[edit]
srbChkMdasAuth
/*
* srbChkMdasAuth - Authenticate a userName/passwd. * * Input - srbConn* conn - From clConnect (). * char *userName and * char *srbAuth - The userName/passwd pair to authenticate. * char *mdasDomain - The MDAS Domaine. * * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbChkMdasAuth (srbConn* conn, char *userName, char *srbAuth, char *mdasDomain);
[edit]
srbChkMdasSysAuth
/*
* srbChkMdasSysAuth - Authenticate a userName/passwd for sys admin access. * * Input - srbConn* conn - From clConnect (). * char *userName and * char *srbAuth - The userName/passwd pair to authenticate. * char *mdasDomain - The MDAS Domain. * * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbChkMdasSysAuth (srbConn* conn, char *userName, char *srbAuth, char *mdasDomain);
[edit]
srbRegisterUserGrp
/*
* srbRegisterUserGrp - Register a user group * * Input - srbConn* conn - From clConnect (). * int catType - catalog type. e,g., MDAS_CATALOG. * char *userGrpName - The name of the user group to register. * char *userGrpPasswd - The user group passwd. * char *userGrpType - The user group type. Currently, at SDSC valid * userType are: * "staff", "sdsc staff", "sdsc staff scientist", * "sdsc senior staff scientist", "pto staff", "ucsd staff" * "student", "sdsc student", "uva student", "project", * "umd student", "public", "sysadmin", " deleted" * char* userGrpAddress - The mailing address of the user group. * char* userGrpPhone - The phone number of the user group. * char* userGrpEmail - The Email address of the user group. * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbRegisterUserGrp (srbConn* conn, int catType, char *userGrpName,
char *userGrpPasswd,
char *userGrpType,
char* userGrpAddress, char* userGrpPhone,
char* userGrpEmail);
[edit]
srbRegisterUser
/*
* srbRegisterUser - Register a user. * * Input - srbConn* conn - From clConnect (). * int catType - catalog type. e,g., MDAS_CATALOG. * char *userName - The name of the user to register. * char *userDomain - The domain of the user to register. * char *userPasswd - The user passwd. * char *userType - The user type. Currently, at SDSC valid userType * are: * "staff", "sdsc staff", "sdsc staff scientist", * "sdsc senior staff scientist", "pto staff", "ucsd staff" * "student", "sdsc student", "uva student", "project", * "umd student", "public", "sysadmin", " deleted" * char* userAddress - The mailing address of the user. * char* userPhone - The phone number of the user. * char* userEmail - The Email address of the user. * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbRegisterUser (srbConn* conn, int catType, char *userName, char *userDomain,
char *userPasswd,
char *userType,
char* userAddress, char* userPhone,
char* userEmail);
[edit]
srbModifyUser
/*
* srbModifyUser - Modify a user info. * * Input - srbConn* conn - From clConnect (). * int catType - catalog type. e,g., MDAS_CATALOG. * * char *dataValue1, char *dataValue2 and int retractionType - * They are used to specify the user attributes to modify. A normal * user may use it to modify his/her own passwd and a limited * set of attributes. A user with MDAS sys admin privilege can * also use these input values to modify other user's attributes. * * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbModifyUser (srbConn* conn, int catType, char *dataValue1, char *dataValue2, int retractionType);
[edit]
srbModifyExtMetaData
/*
* srbModifyExtMetaData - Modify an extensible metadata table in MCAT.
*
* Input - srbConn* conn - From srbConnect ().
* int catType - catalog type. e,g., MDAS_CATALOG.
*
* char *dataValue1 ... char *dataValue5 and int retractionType -
* They are used to specify the table and rows attributes to modify/add/delete.
(below, we give the semantics for the data_values for the
supported retraction_type (they are comma separted) D_DELETE_FROM_EXTMD_TABLE data_1 contains table name
data_2 contains one or more attribute names in that table
separated by | (only one set)
data_3 contains the comparison-values corresponding to
those attributes. data_3 can have many rows/statements
separated by new_line. each will be deleted.
Attribute names: data_id,user_id, and collection_id
are keywords and will be substituted. Use 0 as place-holder
D_INSERT_INTO_EXTMD_TABLE data_1 contains table name
data_2 contains one or more attribute in that table
data_3 contains the values corresponding to
those attributes.data_3 can have many rows/statements.
Separate rows by new_line. New rows are inserted.
Attribute names data_id,user_id,time_val, and collection_id
are keywords and will be substituted. Use 0 as place-holder
D_MODIFY_IN_EXTMD_TABLE
data_1 contains table name
data_2 contains one or more attribute in that table and
data_3 contains the values corresponding to
those attributes.these are new values to be inserted
data_4 contains one or more attribute in that table and
data_5 contains the comparison-values corresponding to
data_4 attributes. These are used to chose the rows.
data_5 and data_3 can have more than one row separated by newline. they should match in number of rows.
Separate rows by new_line.
Attribute names data_id,user_id,time_val, and collection_id
are keywords and will be substituted. Use 0 as place-holder
* * * Output - Returns 0 - success. * Returns negative - failure. */
extern int srbModifyExtMetaData (srbConn* conn, int catType, char *dataName, char *collName, char *dataValue1, char *dataValue2, char *dataValue3, char *dataValue4, char *dataValue5, int retractionType);
[edit]
srbGetPrivUsers
/*
* srbGetPrivUsers - Read the privileged users list and put it in * a user supplied char srbUserList[MAX_TOKEN][MAX_TOKEN]. * * Input - srbConn* conn - From clConnect (). * int catalog - The catalog type. e.g., MDAS_CATALOG * mdasC_sql_result_struct *srbUserList - A pointer to a user supplied * mdasC_sql_result_struct. * int rowsWanted - The number of rows to be returned. * * Output - * 0 - success; myresult->continuation_index >= 0, ==> more results from * the query. Use srbGetMoreRows() to retrieve more rows. * Returns a negative value upon failure. */
extern int srbGetPrivUsers(srbConn *conn, int catalog, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
srbGetMoreRows
/*
* srbGetMoreRows - Get more rows of result from a srbGetDatasetInfo, * srbGetDataDirInfo, srbListCollect or srbGetPrivUsers calls and put * the results in a user supplied mdasC_sql_result_struct. * * Input - srbConn* conn - From clConnect (). * int catalog - The catalog type. e.g., MDAS_CATALOG * mdasC_sql_result_struct *myresult - A pointer to a user supplied * mdasC_sql_result_struct. * int contDesc - The continuation descriptor. This is a non negative * integer returned from a srbGetDatasetInfo, srbGetDataDirInfo, * srbListCollect or srbGetPrivUsers call as * myresult->continuation_index. * int rowsWanted - The number of rows to be returned. * * Output - Returns 0 upon success. * Returns a negative value upon failure. */
extern int srbGetMoreRows(srbConn *conn, int catalog, int contDesc, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
srbGenGetMoreRows
/*
* srbGenGetMoreRows -This is a more compact form of srbGetMoreRows. * The result is packed with packMsg. * Get more rows of result from a srbGetDatasetInfo, * srbGetDataDirInfo, srbListCollect or srbGetPrivUsers calls and put * the results in a user supplied mdasC_sql_result_struct. * * Input - srbConn* conn - From srbConnect (). * int catalog - The catalog type. e.g., MDAS_CATALOG * mdasC_sql_result_struct *srbUserList - A pointer to a user supplied * mdasC_sql_result_struct. * int contDesc - The continuation descriptor. This is a non negative * integer returned from a srbGetDatasetInfo, srbGetDataDirInfo, * srbListCollect or srbGetPrivUsers call as * myresult->continuation_index. * int rowsWanted - The number of rows to be returned. * * Output - Returns 0 upon success. * Returns a negative value upon failure. */
extern int srbGenGetMoreRows(srbConn *conn, int catalog, int contDesc, mdasC_sql_result_struct *myresult, int rowsWanted);
[edit]
freeSqlResult
extern void freeSqlResult (mdasC_sql_result_struct *myresult);
/* clearSqlResult - Clear the content of myresult. Myresult is not freed
* itself. * * Input : mdasC_sql_result_struct *myresult - The mdasC_sql_result_struct * to be cleared. * * Output - None */
extern void clearSqlResult (mdasC_sql_result_struct *myresult);
[edit]
printSqlResult
/* printSqlResult - Print the content of myresult.
* * Input : mdasC_sql_result_struct *myresult - The mdasC_sql_result_struct * to be printed. * * Output - None */
extern void printSqlResult (mdasC_sql_result_struct *myresult);
[edit]
srbRegisterLocation
/*
* srbRegisterLocation - register location information * * Input - srbConn* conn - From srbConnect (). * char *locName - The location name. * char *fullAddr - Full Address. * char *parentLoc - Parent location * char *serverUser - Server User * char *serverUserDomain - Server User Domain * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbRegisterLocation(srbConn* conn,
char *locName,
char *fullAddr,
char *parentLoc,
char *serverUser,
char *serverUserDomain);
[edit]
srbIngestToken
/*
* srbIngestToken - Ingest Token * * Input - srbConn* conn - From srbConnect (). * char *typeName - The type name. * char *newValue - The new value. * char *parentValue - Parent value. * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbIngestToken(srbConn* conn,
char *typeName,
char *newValue,
char *parentValue);
[edit]
srbRegisterResource
/*
* srbRegisterResource - Register Resource * * Input - srbConn* conn - From srbConnect (). * char *rescName - The resource name. * char *rescType - Resource type. * char *location - Location. * char *phyPath - Physical Path. * char *class - class. * int size - size. * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbRegisterResource(srbConn* conn,
char *rescName,
char *rescType,
char *location,
char *phyPath,
char *res_class,
int size);
[edit]
srbRegisterLogicalResource
/*
* srbRegisterLogicalResource - Register Logical Resource * * Input - srbConn* conn - From srbConnect (). * char *rescName - The resource name. * char *rescType - Resource type. * char *phyResc - Physical resource. * char *phyPath - Physical path. * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbRegisterLogicalResource(srbConn* conn,
char *rescName,
char *rescType,
char *phyResc,
char *phyPath);
[edit]
srbRegisterReplicateResourceInfo
/*
* srbRegisterReplicateResourceInfo * * Input - srbConn* conn - From srbConnect (). * char *physicalRescName - The physical resource name. * char *rescType - Resource type. * char *oldLogicalRescName - old logical resource name. * char *indefaultPath - Indefault Path. * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbRegisterReplicateResourceInfo( srbConn* conn,
char *physicalRescName,
char *rescType,
char *oldLogicalRescName,
char *indefaultPath);
[edit]
srbDeleteValue
/*
* srbDeleteValue - Delete a Value; a single MCAT entry * * Input - srbConn* conn - From srbConnect (). * int valueType - the value (token) type. * char *deleteValue - The value (name) that is being deleted. * Output - Returns 0 if successful. * Returns a negative value upon failure. */
int srbDeleteValue(srbConn* conn,
int valueType,
char *deleteValue);
[edit]
srbSetupSessionPublicKey
/*
* srbSetupSessionPublicKey - Get the MCAT-enabled server's public key * in preparation for transferring encryptioned information. * Also see the sscSetupSessionPublicKey library routine. * * Input - srbConn* conn - From srbConnect (). * * * Output - Returns positive value upon success (strlen of publicKey) * Returns a NULL or negative value for some failures. * publicKey - a string representation of the current public key, * If server-side secure communication is not supported, * publicKey will instead contain an error message string. */
extern int srbSetupSessionPublicKey (srbConn *conn, char *publicKey);
[edit]
srbSetupSession
/*
* srbSetupSession - set up a session (for encryption) with the * MCAT-enabled server * Also see the sscSetupSession library routine. * * Input - srbConn* conn - From srbConnect (). * char* sessionKey - a string representation of the session key * from sscSetupSession (encrypted in the * public key) * * Output - Returns 0 if successful. * Returns a negative value upon failure. */
extern int srbSetupSession (srbConn *conn, char *sessionKey);
