MCAT API

From SRB

The following are the API calls that interact with the MCAT.

Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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


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

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

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

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

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