User-defined data (UDD) is the type of data, which is not found in PDB and mmCIF coordinate files, which does not have predefined meaning and which becomes known only at run-time. UDD may be saved into and retrieved from MMDB binary files.
UDD are allowed on any level of the coordinate hierarchy. This means that arbitrary number of UDDs may be added to any atom, any residue and any model. In MMDB, UDDs are identified by three characteristics:| Identification | Description | ||||||||
| math type | real numbers, integers or strings | ||||||||
| registration type | coordinate hierarchy level:
|
||||||||
| name | a unique UDD name |
| Function | Purpose |
| CMMDBManager::RegisterUDInteger | Registering a user-defined data of integer type.
|
| CMMDBManager::RegisterUDReal | Registering a user-defined data of real type.
|
| CMMDBManager::RegisterUDString | Registering a user-defined data of string type.
|
| CMMDBManager::GetUDDHandle | Obtaining a handle for already registered UDD..
|
int CMMDBManager::RegisterUDInteger ( |
int udr_type, |
The function registers an integer User-Defined Data for the level of coordinate hierarchy identified by udr_type under name UDDataID.
The function returns a UDD handle, which provides further access to the registered UDD. The handle is non-zero and unique. Zero return means registration failure. If the function returns UDDATA_WrongUDRType it means that udr_type was given a wrong value (this will not happen if you use constants UDR_XXXX described above.
Register two UDD integers for atoms,
named "color" and "history", then write and read them:
PCMMDBManager MMDB;
PCAtom A;
int uddHandle1,uddHandle2, V,rc;
. . . . . . . . . . . . . . . . . . . . . . . .
uddHandle1 = MMDB->RegisterUDInteger ( UDR_ATOM,"color" );
uddHandle2 = MMDB->RegisterUDInteger ( UDR_ATOM,"history" );
if ((!uddHandle1) || (!uddHandle2)) {
printf ( " registration failed.\n" );
exit ( 1 );
}
if ((uddHandle1==UDDATA_WrongUDRType) ||
(uddHandle2==UDDATA_WrongUDRType)) {
printf ( " wrong registration type used.\n" );
exit ( 2 );
}
A = MMDB->GetAtom ( "/1/A/33(SER).B/CA[C].A" );
if (A->PutUDData(uddHandle1,12)!=UDDATA_Ok) {
printf ( " failed to store UDD 'color'.\n" );
exit ( 3 );
}
if (A->PutUDData(uddHandle2,22)!=UDDATA_Ok) {
printf ( " failed to store UDD 'history'.\n" );
exit ( 4 );
}
rc = A->GetUDData ( uddHandle1,V );
switch (rc) {
case UDDATA_WrongUDRType :
printf ( " wrong UDD registration type when accessing 'color'.\n" );
exit ( 5 );
case UDDATA_WrongHandle :
printf ( " wrong UDD handle when accessing 'color'.\n" );
exit ( 6 );
case UDDATA_NoData :
printf ( " UDD 'color' not found.\n" );
exit ( 7 );
case UDDATA_Ok :
printf ( " UDD 'color' is set to %i.\n",V );
break;
default :
printf ( " Unknown UDD return %i.\n",rc );
exit ( 8 );
}
A->GetUDData ( uddHandle2,V );
printf ( " UDD 'history' is set to %i.\n",V );
. . . . . . . . . . . . . . . . . . . . . . . . . .
int CMMDBManager::RegisterUDReal ( |
int udr_type, |
The function registers a real-type User-Defined Data for the level of coordinate hierarchy identified by udr_type under name UDDataID.
The function is conceptually identical to CMMDBManager::RegisterUDInteger.int CMMDBManager::RegisterUDString ( |
int udr_type, |
The function registers a string-type User-Defined Data for the level of coordinate hierarchy identified by udr_type under name UDDataID.
The function is conceptually identical to CMMDBManager::RegisterUDInteger.int CMMDBManager::GetUDDHandle ( |
int udr_type, |
The function retrieves the UDD handle for the specified data. The UD data must be already registered with either of functions CMMDBManager::RegisterUDInteger, CMMDBManager::RegisterUDReal or CMMDBManager::RegisterUDString. The function accepts exactly the same parameters as those used at registration.
A positive return represents the UDD handle, which may be then used for retrieving the UDD (cf. example). A zero return means that the UDD was not registered (no handle found). Return UDDATA_WrongUDRType means that udr_type was given a wrong value (this will not happen if you use constants UDR_XXXX described above.
NOTE : The UDD handles may change after reading from MMDB binary file. It is therefore advisable that you do not store UDD handles in the file, but rather obtain them from GetUDDHandle as necessary.