📄 rm_ch3.htm
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta name="generator" content="HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org"><meta http-equiv="content-type" content="text/html; charset=us-ascii"><meta name="Generator" content="Microsoft Word 97"><title>db.* Reference Manual Chapter 3</title></head><body><h1><a name="Function" id="Function"></a>Chapter 3<br>Function Descriptions</h1><h2><a name="Introduction" id="Introduction"></a>3.1Introduction</h2><p><font size="2">This chapter contains descriptions of theapplication program interface (API) of all <b><i>db.*</i></b>runtime library functions. The page headers for each descriptioncontain the function name and title. The Prototypes section gives asynopsis of the actual function declaration (not how it is called).The Parameters section describes all parameters.</font></p><blockquote><b><i>Note:</i></b> The parameters for file, record,field, and set identifiers appear in uppercase. This indicates thatnormally the corresponding C constant created by <b>ddlp</b> in<<b>dbname</b>><b>.h</b> is passed to thefunction.</blockquote><p><font size="2">The Description explains all of the function'soperational details. Any Currency Changes are listed usingassignment statements in the order in which the changes occur. Thenotation "curr_own[<i>SET</i>]," is read "current owner of<i>SET</i>". For time-stamped records and sets, the timestamps inthe currency table are also updated by the navigation functionswhen the database addresses are updated unless otherwise noted. Inthe event of a user or system error, the changes to the currencytable are not made.</font></p><p>When the multi-user library runs in shared mode, many functionshave Locking Requirements. The lowest level is no locking, or"None." The next level is "None, but may be old or deleted data,"(see section 7.3.2, "Read Locks," in the <b><i>db.*</i></b><i>User's Guide</i>). The third level is "Read lock required." Thehighest level is "Write lock required." These requirements may beignored in the single-user library, or in the multi-user libraryopened in exclusive or one-user mode. Any files with exclusivelocks are at the highest locking level.</p><p>In the Return Codes section, the most common status and errorcodes are listed, often with a possible explanation for theiroccurrences. We do not list all possible codes, but only those thattend to occur most often.</p><p>Related functions are identified in the See Also section.</p><p>An Example section is provided for each function. The example isintended to illustrate how the function is called, not necessarilyhow to best use the function. In some cases, the example is brief.However, it should be sufficient to show how the call is made.Chapter 5, "Database Manipulation," Chapter 6, "TransactionProcessing," and Chapter 7, "Multi-User Database Control," of the<b><i>db.*</i></b> <i>User's Guide</i> provide many more examplesof <b><i>db.*</i></b> functions.</p><h2><a name="Unicode" id="Unicode"></a>3.2 Unicode Prototypes</h2><p><font size="2">The <b><i>db.*</i></b> product supports Unicode.The effect on the <b>d_</b> API is that the prototypes for some ofthose functions are different in the Unicode version than in thestandard version. These are all functions with (char *) arguments.In the majority of these, (char *) becomes (wchar_t *). When thischange is necessary, it is noted in the Prototypes section for theindividual function. Those requiring a Unicode change aresummarized in Table 3-1. Note, however, that several functions thattake the (char *) arguments do <i>not</i> change in the Unicodeversion. These are listed in Table 3-2.</font></p><blockquote><b><i>Note:</i></b> Unicode and non-Unicode functionprototypes may not be mixed (for those functions that change). Only(char *) is available in an ASCII <b><i>db.*</i></b> runtime, andonly (wchar_t *) is available in a Unicode <b><i>db.*</i></b>runtime.</blockquote><p align="center"><b><font size="2">Table 3-1. Functions Requiringa Data Type Change for Unicode</font></b></p><table cellspacing="0" border="0" cellpadding="7" width="542"><tr><td width="50%" valign="top"><p><b><font size="2">d_checkid<br>d_ctbpath<br>d_dbdpath<br>d_dbfpath<br>d_dbini<br>d_dblog<br>d_dbnum<br>d_dbtaf<br>d_dbtmp<br>d_dbuserid</font></b></p></td><td width="50%" valign="top"><p><b><font size="2">d_dbver<br>d_destroy<br>d_iopen<br>d_lmclear<br>d_lmstat<br>d_lockmgr<br>d_open*<br>d_renfile<br>d_trbegin</font></b></p></td></tr></table><div style="margin-left: 4em"><p><font size="2">*The <b>d_open</b> function has two characterstring arguments. For the Unicode version, only one of those twoarguments changes from (char *) to (wchar_t *). The argument forthat function's database open mode remains (char *), becausearguments for locking modes and database access modes usually havethat data type.</font></p></div><p align="center"><b>Table 3-2. Functions (Using char) that Need NoChange for Unicode</b></p><table cellspacing="0" border="0" cellpadding="7" width="542"><tr><td width="50%" valign="top"><p><b><font size="2">d_keylock<br>d_keylstat<br>d_mapchar<br>d_reclock</font></b></p></td><td width="50%" valign="top"><p><b><font size="2">d_reclstat<br>d_setlock<br>d_setlstat</font></b></p></td></tr></table><h2><a name="Summary" id="Summary"></a>3.3 Summary Listing of d_Functions</h2><p><font size="2">The following table lists alphabetically all the<b>d_</b> functions and their prototypes, along with briefdescriptions. All functions have <b>int</b> as their returntypes.</font></p><p align="center"><b><font size="2">Table 3-3. Alphabetical Listingof the d_ Functions</font></b></p><p><font size="2">Function Prototype/<br>Description</font></p><p><font size="2">int <b>d_checkid</b>(char *<i>id</i>, DB_TASK*<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Check a DBUSERID for validity</font></p><p><font size="2">int <b>d_close</b>(DB_TASK *<i>task</i>)<br>Close all databases</font></p><p><font size="2">int <b>d_closeall</b>(DB_TASK *<i>task</i>)<br>Close all open files</font></p><p><font size="2">int <b>d_closetask</b>(DB_TASK * <i>task</i>)<br>Close a database task</font></p><p><font size="2">int <b>d_cmstat</b>(int <i>SET</i>, DB_TASK*<i>task</i>)<br>Test timestamp status of current member</font></p><p><font size="2">int <b>d_cmtype</b>(int <i>SET</i>, int*<i>rectype</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get record type of current member</font></p><p><font size="2">int <b>d_connect</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Connect current record to set</font></p><p><font size="2">int <b>d_costat</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Test timestamp status of current owner</font></p><p><font size="2">int <b>d_cotype</b>(int <i>SET</i>, int*<i>rectype</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get record type of current owner</font></p><p><font size="2">int <b>d_crget</b>(DB_ADDR *<i>dba</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Get database address of current record</font></p><p><font size="2">int <b>d_crread</b>(long <i>FIELD</i>, void*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Read data from field of current record</font></p><p><font size="2">int <b>d_crset</b>(DB_ADDR *<i>dba</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Set database address of current record</font></p><p><font size="2">int <b>d_crstat</b>(DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Test timestamp status of current record</font></p><p><font size="2">int <b>d_crtype</b>(int *<i>rectype</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Get record type of current record</font></p><p><font size="2">int <b>d_crwrite</b>(long <i>FIELD</i>, void*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Write to field in current member</font></p><p><font size="2">int <b>d_csmget</b>(int <i>SET</i>, DB_ADDR*<i>dba</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get database address of current member</font></p><p><font size="2">int <b>d_csmread</b>(int <i>SET</i>, long<i>FIELD</i>, void *<i>value</i>, DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Read data from field of current member</font></p><p><font size="2">int <b>d_csmset</b>(int <i>SET</i>, DB_ADDR*<i>dba</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Set database address of current member</font></p><p><font size="2">int <b>d_csmwrite</b>(int <i>SET</i>, long<i>FIELD</i>, const void *<i>value</i>, DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Write to field in current member</font></p><p><font size="2">int <b>d_csoget</b>(int <i>SET</i>, DB_ADDR*<i>dba</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get database address of current owner</font></p><p><font size="2">int <b>d_csoread</b>(int <i>SET</i>, long<i>FIELD</i>, void *<i>value</i>, DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Read data from field of current owner</font></p><p><font size="2">int <b>d_csoset</b>(int <i>SET</i>, DB_ADDR*<i>dba</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Set database address of current owner</font></p><p><font size="2">int <b>d_csowrite</b>(int <i>SET</i>, long<i>FIELD</i>, const void *<i>value</i>, DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Write to field in current owner</font></p><p><font size="2">int <b>d_csstat</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Test timestamp status of current set</font></p><p><font size="2">int <b>d_ctbpath</b>(const char *<i>path</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the country table path variable</font></p><p><font size="2">int <b>d_curkey</b>(DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Set key positions for keys in current record</font></p><p><font size="2">int <b>d_dbdpath</b>(const char *<i>path</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set database dictionary path variable</font></p><p><font size="2">int <b>d_dbfpath</b>(const char *<i>path</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set database files path variable</font></p><p><font size="2">int <b>d_dbini</b>(const char *<i>dir_name</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the directory in which to find the <b><i>db.*</i></b>initialization file</font></p><p><font size="2">int <b>d_dblog</b>(const char *<i>log</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the path to the database log file</font></p><p><font size="2">int <b>d_dbnum</b>(const char *<i>dbname</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Get the database number from the database name</font></p><p><font size="2">int <b>d_dbtaf</b>(const char *<i>taf</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the TAF path variable</font></p><p><font size="2">int <b>d_dbtmp</b>(const char *<i>tmp</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the DBTMP path variable</font></p><p><font size="2">int <b>d_dbuserid</b>(const char *<i>id</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Set the database user ID</font></p><p><font size="2">int <b>d_dbver</b>(char *<i>fmt</i>, char*<i>buf</i>, int <i>len</i>)<b><br></b> Unicode version: (char *)changes to (wchar_t *)<br>Return runtime version information</font></p><p><font size="2">int <b>d_decode_dba</b>(DB_ADDR <i>dba</i>, short*<i>file</i>, unsigned long *<i>slot</i>)<br>Decode database address</font></p><p><font size="2">int <b>d_delete</b>(DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Delete current record</font></p><p><font size="2">int <b>d_destroy</b>(const char *<i>dbname</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Destroy database files</font></p><p><font size="2">int <b>d_discon</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Disconnect current member from set</font></p><p><font size="2">int <b>d_disdel</b>(int <i>dbn</i>, DB_TASK*<i>task</i>)<br>Disconnect and delete current record</font></p><p><font size="2">int <b>d_encode_dba</b>(short <i>file</i>,unsigned long <i>slot</i>, DB_ADDR *<i>dba</i>)<br>Encode database address</font></p><p><font size="2">int <b>d_fillnew</b>(int <i>REC</i>, const void*<i>value</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Create and fill new record</font></p><p><font size="2">int <b>d_findco</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Find current owner of current record</font></p><p><font size="2">int <b>d_findfm</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Find first member of set</font></p><p><font size="2">int <b>d_findlm</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Find last member of set</font></p><p><font size="2">int <b>d_findnm</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Find next member of set</font></p><p><font size="2">int <b>d_findpm</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Find previous member of set</font></p><p><font size="2">int <b>d_fldnum</b>(int *<i>index_num</i>, long<i>FIELD</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Convert the field's <b>ddlp</b> <b>#define</b> into the field tableindex</font></p><p><font size="2">int <b>d_freeall</b>(DB_TASK *<i>task</i>)<br>Free all read-locked files</font></p><p><font size="2">int <b>d_gtscm</b>(int <i>SET</i>, unsigned long*<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get last access timestamp of current member</font></p><p><font size="2">int <b>d_gtsco</b>(int <i>SET</i>, unsigned long*<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get last access timestamp of current owner</font></p><p><font size="2">int <b>d_gtscr</b>(unsigned long *<i>ts</i>,DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get last access timestamp of current record</font></p><p><font size="2">int <b>d_gtscs</b>(int <i>SET</i>, unsigned long*<i>ts</i>, DB_TASK *<i>task</i>, int <i>dbn</i>)<br>Get last access timestamp for set</font></p><p><font size="2">int <b>d_iclose</b>(DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Close database incrementally</font></p><p><font size="2">int <b>d_initfile</b>(int <i>FILEID</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Initialize database file</font></p><p><font size="2">int <b>d_initialize</b>(DB_TASK *<i>task</i>, int<i>dbn</i>)<br>Initialize database</font></p><p><font size="2">int <b>d_internals</b>(DB_TASK *<i>task</i>, int<i>topic</i>, int <i>id</i>, int <i>elem</i>, void *<i>ptr</i>,unsigned <i>size</i>)<br>Access internal <b><i>db.*</i></b> data</font></p><p><font size="2">int <b>d_iopen</b>(const char *<i>dbnames</i>,DB_TASK *<i>task</i>)<br>Unicode version: (char *) changes to (wchar_t *)<br>Open one or more databases incrementally</font></p><p><font size="2">int <b>d_ismember</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Determine whether the current record is a member of aset</font></p><p><font size="2">int <b>d_isowner</b>(int <i>SET</i>, DB_TASK*<i>task</i>, int <i>dbn</i>)<br>Determine whether the current record is the owner of aset</font></p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -