1dnl $Id: m4.db,v 10.194 2008/01/23 21:15:45 sarette Exp $ 2 3include(m4/m4.init) 4include(m4/m4.html) 5include(m4/m4.flags) 6include(m4/m4.err) 7include(m4/m4.ret) 8ifelse(M4PRODUCT, XML, [include(m4/m4.xml)]) 9include(m4/m4.links) 10ifelse(M4PRODUCT, XML, [include(m4/m4.xmllinks)]) 11 12dnl Product names 13define(m4_am, m4_db Data Store) 14define(m4_cam, m4_db Concurrent Data Store) 15define(m4_ha, m4_db High Availability) 16define(m4_tam, m4_db Transactional Data Store) 17define(m4_xml, m4_db XML) 18define(m4_sxml, BDB XML) 19 20dnl Standards 21define(m4_ansic_name, [ANSI C X3.159-1989 (ANSI C)]) 22define(m4_posix1_name, [IEEE/ANSI Std 1003.1 (POSIX)]) 23 24dnl m4_incextra -- 25dnl API "includes". C/C++ have standard includes (although the 26dnl XML's header file includes the standard C++ header for you). 27dnl 28dnl $1: "XML" use the XML include rather than the C++ one. 29dnl else, if it's C/C++ it's a leading #define, it comes first. 30define(m4_incextra, [dnl 31ifelse(M4API, CXX_API, [dnl 32ifelse($1, XML, [m4_include(DbXml.hpp)], [$1 33m4_include(db_cxx.h)])], 34[$1 35m4_include(db.h)])]) 36 37dnl Build the reference, and append the word "method". 38dnl $1: name 39define(m4_refT, [m4_ref($1) method]) 40 41dnl Build the reference, and append the correct word "structure" or "object". 42dnl $1: name 43define(m4_refO, [m4_ref($1) ifelse(M4API, CXX_API, object, structure)]) 44 45dnl Some methods aren't available in C++. 46dnl $1: method 47define(m4_no_such_method, [dnl 48m4_p([The m4_refT($1) is not included in the m4_db C++ API.]) 49m4_page_footer 50m4exit]) 51define(m4_no_such_class, [dnl 52m4_p([The $1 class is not included in the m4_db C++ API.]) 53m4_page_footer 54m4exit]) 55 56dnl ################################################################### 57dnl OBJECT-IN-ALLOCATED MEMORY MACRO: 58dnl #1: the allocated object 59dnl ################################################################### 60define(m4_alloc, [m4_p([dnl 61$1 are stored in allocated memory. If application-specific allocation 62routines have been declared (see m4_ref(dbenv_set_alloc) for more 63information), they are used to allocate the memory; otherwise, the 64standard C library m4_manref(malloc, 3) is used. The caller is 65responsible for deallocating the memory. To deallocate the memory, free 66the memory reference; references inside the returned memory need not be 67individually freed.])]) 68 69dnl ################################################################### 70dnl BULK GET MEMORY 71dnl ################################################################### 72define(m4_bulk_mem, [dnl 73The buffer to which the m4_arg(data) parameter refers must be provided 74from user memory (see m4_ref(DB_DBT_USERMEM)). The buffer must be at 75least as large as the page size of the underlying database, aligned for 76unsigned integer access, and be a multiple of 1024 bytes in size. If 77the buffer size is insufficient, then upon return from the call the size 78field of the m4_arg(data) parameter will have been set to an estimated 79buffer size, m4_err_mem_insufficient. (The size is an estimate as the 80exact size needed may not be known until all entries are read. It is 81best to initially provide a relatively large buffer, but applications 82should be prepared to resize the buffer as necessary and repeatedly call 83the method.)]) 84 85dnl ################################################################### 86dnl DB_HOME/set_data_dir 87dnl #1: the function name 88dnl #2: "0" if DB_ENV function, "1" if DB function. 89dnl 90dnl Several DB_ENV/DB functions are affected by DB_HOME and the data 91dnl directory value. 92dnl ################################################################### 93define(m4_data_location, [m4_p([ifelse([$2], 0, [The ], [dnl 94If the database was opened within a database environment, the]) 95environment variable m4_envvar(DB_HOME) may be used as the path of the 96database environment home.]) 97m4_p([m4_ref($1) is affected by any database directory specified using 98the m4_refT(dbenv_set_data_dir), or by setting the "set_data_dir" string 99in the environment's m4_ref(DB_CONFIG) file.])]) 100 101dnl When the method has a corresponding DB_CONFIG file entry. 102dnl #1: method 103dnl #2: value 104dnl #3: matching string 105dnl #4: syntax 106dnl #5: "no" if doesn't overrule other configuration. 107define(m4_env_config, [m4_p([dnl 108The database environment's $2 may also be configured using the 109environment's m4_ref(DB_CONFIG) file. The syntax of the entry in that 110file is a single line with the string "$3", one or more whitespace 111characters, and $4. 112ifelse([$5], no,, [dnl 113Because the m4_ref(DB_CONFIG) file is read when the database environment 114is opened, it will silently overrule configuration done before that 115time.])])]) 116 117define(m4_env_flags, [dnl 118m4_idefz([use @environment constants in naming]) 119m4_tag(m4_idef(DB_USE_ENVIRON), [dnl 120The m4_db process' environment may be permitted to specify information 121to be used when naming files; see m4_link(M4RELDIR/ref/env/naming, 122[m4_db File Naming]). Because permitting users to specify which files 123are used can create security problems, environment information will be 124used in file naming for all users only if the DB_USE_ENVIRON 125flag is set.]) 126m4_tag(m4_idef(DB_USE_ENVIRON_ROOT), [dnl 127The m4_db process' environment may be permitted to specify information 128to be used when naming files; see m4_link(M4RELDIR/ref/env/naming, 129[m4_db File Naming]). Because permitting users to specify which files 130are used can create security problems, if the 131DB_USE_ENVIRON_ROOT flag is set, environment information will 132be used for file naming only for users with appropriate permissions (for 133example, users with a user-ID of 0 on UNIX systems).])]) 134 135define(m4_env_flags_any, [m4_p([dnl 136The m4_ref($1) flag may be used to configure m4_db at any time during 137the life of the application.])]) 138 139define(m4_env_flags_open, [m4_p([dnl 140The m4_ref($1) flag may be used to configure m4_db only $2 the 141m4_refT(dbenv_open) is called.])]) 142 143dnl ################################################################### 144dnl DOCUMENT AN UNDERLYING FUNCTION: 145dnl m4_underfunc -- 146dnl #1 function name 147dnl #2 underlying function name 148dnl #3 utility name 149dnl ################################################################### 150define(m4_underfunc, [dnl 151ifelse(M4API, C_API, [m4_p([dnl 152The m4_refT($1) is the underlying method used by the m4_ref($3) utility. 153See the m4_ref($3) utility source code for an example of using m4_ref($2) 154in a m4_posix1_name environment.])]) 155ifelse(M4API, UTILITY, [m4_p([dnl 156The m4_refT($1) is the underlying method used by the m4_ref($3) utility. 157See the m4_ref($3) utility source code for an example of using m4_ref($2) 158in a m4_posix1_name environment.])])]) 159 160dnl ################################################################### 161dnl METHOD MODIFIES DB_ENV, NOT DB 162dnl m4_really_dbenv -- 163dnl #1 DB function name 164dnl #2 DB_ENV function name 165dnl ################################################################### 166define(m4_really_dbenv, [m4_p([dnl 167For m4_ref(Db) handles opened inside of m4_db environments, calling the 168m4_refT($1) affects the entire environment and is equivalent to calling 169the m4_refT($2).])]) 170 171dnl ################################################################### 172dnl Jump functions 173dnl m4_ansi_func ANSI C function replacement. 174dnl m4_posix_func POSIX standard 175dnl m4_ret_internal Return value. 176dnl #1: function name 177dnl ################################################################### 178define(m4_ansi_func, [m4_p([dnl 179Replace m4_db calls to the ANSI C X3.159-1989 (ANSI C) standard 180m4_bold($1) function with m4_arg(func_$1), which must conform to the 181standard interface specification.])]) 182 183define(m4_posix_func, [m4_p([dnl 184Replace m4_db calls to the m4_posix1_name m4_bold($1) function with 185m4_arg(func_$1), which must conform to the standard interface 186specification.])]) 187 188define(m4_ret_internal, [m4_p([dnl 189The m4_arg($1) function must return the value of m4_envvar(errno) on 190failure and 0 on success.])]) 191 192define(m4_param_replace, [dnl 193m4_parambegin 194m4_param([$1], [dnl 195The m4_arg([$1]) parameter is the replacement function. It must conform 196to the standard interface specification.]) 197m4_paramend]) 198 199dnl ################################################################### 200dnl Stat print functions 201dnl #1: function 202dnl #2: type of statistics 203dnl #3: stat function that lists the default fields 204dnl #4: "no" if m4_pf_description call isn't needed 205dnl ################################################################### 206define(m4_stat_print, [dnl 207ifelse($4, no,, m4_pf_description(m4_ref($1))) 208m4_p([dnl 209The m4_refT($1) displays the 210ifelse($2,, [default statistical information.], 211[$2 statistical information, as described for the m4_refT($3).]) 212The information is printed to a specified output channel (see the 213m4_refT(dbenv_set_msgfile) for more information), or passed to an 214application callback function (see the m4_refT(dbenv_set_msgcall) for 215more information).]) 216ifelse($1, dbh_stat_print, 217 m4_when($1, before, dbh_open), m4_when($1, before, dbenv_open)) 218m4_return($1, std) 219m4_parambegin 220m4_param(flags, [dnl 221m4_sf_or_may(0) 222m4_tagbegin 223ifelse($1, dbh_stat_print, [dnl 224m4_tag(m4_idef(DB_FAST_STAT), [dnl 225Return only the values which do not require traversal of the database. 226Among other things, this flag makes it possible for applications to 227request key and record counts without incurring the performance penalty 228of traversing the entire database.])]) 229m4_tag(m4_idef(DB_STAT_ALL), [dnl 230Display all available information.]) 231ifelse($1, dbh_stat_print,, [dnl 232m4_tag(m4_idef(DB_STAT_CLEAR), [dnl 233Reset statistics after displaying their values.])]) 234ifelse($1, lock_stat_print, [dnl 235m4_tag(m4_idef(DB_STAT_LOCK_CONF), [dnl 236Display the lock conflict matrix.]) 237m4_tag(m4_idef(DB_STAT_LOCK_LOCKERS), [dnl 238Display the lockers within hash chains.]) 239m4_tag(m4_idef(DB_STAT_LOCK_OBJECTS), [dnl 240Display the lock objects within hash chains.]) 241m4_tag(m4_idef(DB_STAT_LOCK_PARAMS), [dnl 242Display the locking subsystem parameters.])]) 243ifelse($1, memp_stat_print, [dnl 244m4_tag(m4_idef(DB_STAT_MEMP_HASH), [dnl 245Display the buffers with hash chains.])]) 246ifelse($1, dbenv_stat_print, [dnl 247m4_tag(m4_idef(DB_STAT_SUBSYSTEM), [dnl 248Display information for all configured subsystems.])]) 249m4_tagend]) 250m4_paramend]) 251 252dnl ################################################################### 253dnl Common destructor language. 254dnl #1: handle 255dnl #2: method 256dnl ################################################################### 257define(m4_destructor, [m4_p([dnl 258The m4_ref($1) handle may not be accessed again after m4_ref($2) is 259called, regardless of its return.])]) 260 261dnl ################################################################### 262dnl The scope of the configuration method. 263dnl #1: method 264dnl ################################################################### 265define(m4_scope_process, [m4_p([dnl 266The m4_refT($1) configures all operations performed by a process and 267all of its threads of control, not operations confined to a single 268database environment.])]) 269define(m4_scope_dbenv, [m4_p([dnl 270The m4_refT($1) configures operations performed using the specified 271m4_ref(DbEnv) handle, not all operations performed on the underlying 272database environment.])]) 273define(m4_scope_env, [m4_p([dnl 274The m4_refT($1) configures a database environment, not only operations 275performed using the specified m4_ref(DbEnv) handle.])]) 276define(m4_scope_env_flags, [m4_p([dnl 277Calling m4_ref($1) with the m4_ref($2) flag affects the 278database environment, including all threads of control accessing the 279database environment.])]) 280define(m4_scope_dbenv_flags, [m4_p([dnl 281Calling m4_ref($1) with the m4_ref($2) flag only affects 282the specified m4_ref(DbEnv) handle (and any other m4_db handles opened 283within the scope of that handle). 284ifelse($3, config, [dnl 285For consistent behavior across the environment, all m4_ref(DbEnv) 286handles opened in the environment must either set the m4_ref($2) flag 287or the flag should be specified in the m4_ref(DB_CONFIG) configuration 288file.])])]) 289define(m4_scope_mpf, [m4_p([dnl 290The m4_refT($1) configures a file in the memory pool, not only 291operations performed using the specified m4_ref(DbMpoolFile) handle.])]) 292define(m4_scope_mpf_flags, [m4_p([dnl 293The m4_ref($1) flag configures a file in the memory pool, not only 294operations performed using the specified m4_ref(DbMpoolFile) handle.])]) 295define(m4_scope_db, [m4_p([dnl 296The m4_refT($1) configures a database, not only operations performed 297using the specified m4_ref(Db) handle.])]) 298define(m4_scope_dbh, [m4_p([dnl 299The m4_refT($1) configures operations performed using the specified 300m4_ref(Db) handle, not all operations performed on the underlying 301database.])]) 302define(m4_scope_tx, [m4_p([dnl 303The m4_refT($1) configures operations performed on the underlying 304transaction, not only operations performed using the specified 305m4_ref(DbTxn) handle.])]) 306 307dnl ################################################################### 308dnl When methods can be called -- general purpose. 309dnl #1: our method name 310dnl #2: before/after 311dnl #3: method name we're scheduling against. 312dnl ################################################################### 313define(m4_when, [m4_p([dnl 314The m4_refT($1) may not be called $2 the m4_refT($3) is called.])]) 315define(m4_when_two, [m4_p([dnl 316The m4_refT($1) may not be called $2 the m4_ref($3) or m4_refT($4)s are 317called.])]) 318 319dnl ################################################################### 320dnl When methods can be called -- specific. 321dnl #1: method 322dnl #2: what happens if config info doesn't match existing object. 323dnl (error, ignored, corrupt, overwrite) 324dnl ################################################################### 325define(m4_when_any, [m4_p([dnl 326The m4_refT($1) may be called at any time during the life of the 327application.])]) 328 329define(m4_when_init, [m4_p([dnl 330Although the m4_refT($1) may be called at any time during the life of 331the application, it should normally be called before making calls to the 332m4_ref(dbenv_create) or m4_refT(dbh_create)s.])]) 333 334define(m4_when_envopen, [m4_p([dnl 335The m4_refT($1) may not be called after the m4_refT(dbenv_open) is 336called. 337ifelse($2, error, [If the database environment already exists when 338m4_ref(dbenv_open) is called, the information specified to m4_ref($1) 339must be consistent with the existing environment or an error will be 340returned.]) 341ifelse($2, ignored, [If the database environment already exists when 342m4_ref(dbenv_open) is called, the information specified to m4_ref($1) 343will be ignored.]) 344ifelse($2, corrupt, [If the database environment already exists when 345m4_ref(dbenv_open) is called, the information specified to m4_ref($1) 346must be consistent with the existing environment or corruption can 347occur.])])]) 348 349define(m4_when_mpfopen, [m4_p([dnl 350The m4_refT($1) may not be called after the m4_refT(memp_fopen) is 351called. 352ifelse($2, error, [If the file is already open in the memory pool when 353m4_ref(memp_fopen) is called, the information specified to m4_ref($1) 354must be consistent with the existing file or an error will be 355returned.]) 356ifelse($2, overwrite, [If the file is already open in the memory pool when 357m4_ref(memp_fopen) is called, the information specified to m4_ref($1) 358will replace the existing information.])])]) 359 360define(m4_when_dbopen, [m4_p([dnl 361The m4_refT($1) may not be called after the m4_refT(dbh_open) is called. 362ifelse($2, ignored, [If the database already exists when 363m4_ref(dbh_open) is called, the information specified to m4_ref($1) will 364be ignored.]) 365ifelse($2, corrupt, [If the database already exists when 366m4_ref(dbh_open) is called, the information specified to m4_ref($1) must 367be the same as that historically used to create the database or 368corruption can occur.])])]) 369 370dnl ################################################################### 371dnl Common getter language. 372dnl #1 method name 373dnl #2 method description 374dnl #3 text description for the variable (empty if same as #2) 375dnl #4 C/C++ variable name 376dnl #5 "reference" if it's a reference to an object, not a value 377dnl ################################################################### 378define(m4_pf_getter, [dnl 379m4_pf_description(m4_ref($1)) 380m4_getter([$1], [$2], [$3], [$4], [$5])]) 381 382define(m4_getter, [dnl 383m4_p([The m4_refT($1) returns the [$2].]) 384ifelse( 385[$1], dbenv_get_open_flags, m4_when([$1], before, dbenv_open), 386[$1], dbh_get_open_flags, m4_when([$1], before, dbh_open), m4_when_any($1)) 387ifelse([$4],,, [dnl 388ifelse([$1], dbh_getenv,, [m4_return($1, std)]) 389m4_parambegin 390m4_param([$4], 391[The m4_refT($1) returns ifelse([$5], reference, a reference to) the 392ifelse([$3],, [$2], [$3]) in m4_arg([$4]).]) 393m4_paramend])]) 394 395dnl ################################################################### 396dnl Stat fields. 397dnl #1 C/C++ type 398dnl #2 field name 399dnl #3 description 400dnl ################################################################### 401define(m4_field, [m4_tag([$1] [$2];, [$3])]) 402 403dnl ################################################################### 404dnl Parameters: 405dnl 406dnl m4_parambegin/end 407dnl m4_param 408dnl #1 C/C++ argument name 409dnl #2 description 410dnl ################################################################### 411define(m4_parambegin, [m4_section(Parameters) m4_tagbegin]) 412define(m4_param, [define([__paramname], [$1]) m4_tag(__paramname, [$2])]) 413define(m4_paramend, m4_tagend) 414 415dnl ################################################################### 416dnl File/Directory parameters get standard Windows UTF-8 language. 417dnl #1: argument name 418dnl #2: argument text 419dnl ################################################################### 420define(m4_param_utf8, [dnl 421m4_param([$1], [$2]) 422m4_p([dnl 423When using a Unicode build on Windows (the default), the m4_arg([$1]) 424argument will be interpreted as a UTF-8 string, which is equivalent to 425ASCII for Latin characters.])]) 426 427dnl ################################################################### 428dnl Standard copy-out language. 429dnl 430dnl m4_param_co -- 431dnl #1: argument 432dnl #2: copied thing 433dnl #3: REF, if it's a reference to the object. 434dnl #4: additional text 435dnl ################################################################### 436define(m4_param_co, [m4_param([$1], [dnl 437The m4_arg([$1]) parameter references memory into which 438ifelse([$3], REF, a pointer to) the $2 is copied.]) $4]) 439 440dnl ################################################################### 441dnl Standard not reentrant language. 442dnl ################################################################### 443define(m4_not_reentrant, [m4_p([dnl 444m4_db is not re-entrant. Callback functions should not attempt to make 445library calls (for example, to release locks or close open handles). 446Re-entering m4_db is not guaranteed to work correctly, and the results 447are undefined.])]) 448 449dnl ################################################################### 450dnl The key/data argument language. 451dnl ################################################################### 452define(m4_param_key, [m4_param(key, [The key m4_ref(Dbt) operated on.])]) 453define(m4_param_data, [m4_param(data, [The data m4_ref(Dbt) operated on.])]) 454 455dnl ################################################################### 456dnl The filesystem mode argument language. 457dnl #1: the subsystem name. 458dnl ################################################################### 459define(m4_param_filemode, [dnl 460m4_param(mode, [dnl 461On Windows systems, the mode parameter is ignored. 462m4_p([dnl 463On UNIX systems or in m4_posix1_name environments, files created by $1 464are created with mode m4_arg(mode) (as described in m4_manref(chmod, 2)) 465and modified by the process' umask value at the time of creation (see 466m4_manref(umask, 2)). Created files are owned by the process owner; the 467group ownership of created files is based on the system and directory 468defaults, and is not further specified by m4_db. System shared memory 469segments created by $1 are created with mode m4_arg(mode), unmodified 470by the process' umask value. If m4_arg(mode) is 0, $1 will use a 471default mode of readable and writable by both owner and group.])])]) 472 473dnl ################################################################### 474dnl Transaction ID arguments. 475dnl 476dnl m4_param_txn -- 477dnl #1: method 478dnl #2: "auto" if there's an auto-commit flag. 479dnl #2: "env" if an environment operation. 480dnl #2: "ro" if a read-only operation 481dnl #3: additional wording 482dnl ################################################################### 483define(m4_param_txn, 484[m4_param(txnid, [dnl 485If the operation is part of an application-specified transaction, the 486m4_arg(txnid) parameter is a transaction handle returned from 487m4_ref(txn_begin); if the operation is part of a m4_cam group, the 488m4_arg(txnid) parameter is a handle returned from 489m4_ref(cdsgroup_begin); otherwise NULL. 490ifelse([$2], ro,, [dnl 491If no transaction handle is 492specified, but the 493ifelse([$2], auto, [DB_AUTO_COMMIT flag is specified], 494[operation occurs in a transactional 495ifelse([$2], env, database environment, database)]), 496the operation will be implicitly transaction protected.]) 497$3])]) 498 499dnl ################################################################### 500dnl Replication lower-level API wording. 501dnl 502dnl m4_repl_lower -- 503dnl #1: method 504dnl ################################################################### 505define(m4_repl_lower, 506[m4_p([The m4_ref($1) method is not called by most replication 507applications. It should only be called by applications implementing 508their own network transport layer, explicitly holding replication group 509elections and handling replication messages outside of the replication 510manager framework.])]) 511 512dnl ################################################################# 513dnl m4_linkjavadoc and supporting macros: 514dnl Link to specific javadoc location in any page. 515dnl #1: package 516dnl #2: class (optional) 517dnl #3: method (optional) 518dnl ################################################################# 519dnl __m4_javasrcref 520dnl #1: package 521define(__m4_javasrcref, [dnl 522ifelse(index($1, com.sleepycat), 0, dnl 523[../../java/translit($1, ., /)], dnl 524ifelse(index($1, java), 0, dnl 525[http://java.sun.com/j2se/1.5.0/docs/api/translit($1, ., /)], $1))]) 526 527define(m4_linkjavadoc, [dnl 528ifelse($#, 3,dnl 529[<a href="__m4_javasrcref($1)/$2.html__OCT__[pathsubst($3, ' ', '%20')]">$2.$3</a>],dnl 530$#, 2,dnl 531[<a href="__m4_javasrcref($1)/$2.html">$2</a>],dnl 532[<a href="__m4_javasrcref($1)/package-summary.html">$1</a>])]) 533