1m4_comment([$Id: m4.tcl,v 11.28 2004/12/16 19:13:05 bostic Exp $]) 2 3define(m4_tcl_version, [m4_bold(berkdb version)]) 4 5define(m4_tcl_env_open, [m4_bold(berkdb env)]) 6define(m4_tcl_env_close, [m4_italic(env) m4_bold(close)]) 7define(m4_tcl_env_remove, [m4_bold(berkdb envremove)]) 8define(m4_tcl_env_dbremove, [m4_italic(env) m4_bold(dbremove)]) 9define(m4_tcl_env_dbrename, [m4_italic(env) m4_bold(dbrename)]) 10 11define(m4_tcl_db_open, [m4_bold(berkdb open)]) 12define(m4_tcl_db_remove, [m4_bold(berkdb dbremove)]) 13define(m4_tcl_db_rename, [m4_bold(berkdb dbrename)]) 14define(m4_tcl_db_close, [m4_italic(db) m4_bold(close)]) 15define(m4_tcl_db_count, [m4_italic(db) m4_bold(count)]) 16define(m4_tcl_db_del, [m4_italic(db) m4_bold(del)]) 17define(m4_tcl_db_get, [m4_italic(db) m4_bold(get)]) 18define(m4_tcl_db_get_join, [m4_italic(db) m4_bold(get_join)]) 19define(m4_tcl_db_get_type, [m4_italic(db) m4_bold(get_type)]) 20define(m4_tcl_db_is_byteswapped,[m4_italic(db) m4_bold(is_byteswapped)]) 21define(m4_tcl_db_join, [m4_italic(db) m4_bold(join)]) 22define(m4_tcl_db_put, [m4_italic(db) m4_bold(put)]) 23define(m4_tcl_db_stat, [m4_italic(db) m4_bold(stat)]) 24define(m4_tcl_db_sync, [m4_italic(db) m4_bold(sync)]) 25define(m4_tcl_db_truncate, [m4_italic(db) m4_bold(truncate)]) 26 27define(m4_tcl_db_cursor, [m4_italic(db) m4_bold(cursor)]) 28define(m4_tcl_dbc_close, [m4_italic(dbc) m4_bold(close)]) 29define(m4_tcl_dbc_del, [m4_italic(dbc) m4_bold(del)]) 30define(m4_tcl_dbc_dup, [m4_italic(dbc) m4_bold(dup)]) 31define(m4_tcl_dbc_get, [m4_italic(dbc) m4_bold(get)]) 32define(m4_tcl_dbc_put, [m4_italic(dbc) m4_bold(put)]) 33 34define(m4_tcl_txn, [m4_italic(env) m4_bold(txn)]) 35define(m4_tcl_txn_commit, [m4_italic(txn) m4_bold(commit)]) 36define(m4_tcl_txn_abort, [m4_italic(txn) m4_bold(abort)]) 37define(m4_tcl_txn_ckp, [m4_italic(env) m4_bold(txn_checkpoint)]) 38 39dnl m4_tcl_arg 40dnl Tcl function argument. 41define(m4_tcl_arg, [__LB__$1__RB__]) 42 43dnl m4_tcl_txnopt: 44dnl 45dnl $1: auto if -auto_commit is a flag 46dnl $1: env if an environment operation 47define(m4_tcl_txnopt, [dnl 48m4_tag([-txn txnid], [dnl 49If the operation is part of an application-specified transaction, the 50m4_arg(txnid) parameter is a transaction handle returned from 51m4_tcl_txn. If no transaction handle is specified, but the 52ifelse([$1], auto, [-auto_commit flag is specified], 53[operation occurs in a transactional 54ifelse([$1], env, database environment, database)]), 55the operation will be implicitly transaction protected.])]) 56 57dnl m4_tcl_ret_error: 58dnl 59define(m4_tcl_ret_error, [m4_p([In the case of error, a Tcl error is thrown.])]) 60 61dnl m4_tcl_ret_previous: 62dnl arg 1: command. 63dnl 64define(m4_tcl_ret_previous, [m4_p([dnl 65Otherwise, the $1 command returns 0 on success, and in the case of error, 66a Tcl error is thrown.])]) 67 68dnl m4_tcl_ret_standard: 69dnl arg 1: command. 70dnl 71define(m4_tcl_ret_standard, [m4_p([dnl 72The $1 command returns 0 on success, and in the case of error, a Tcl error 73is thrown.])]) 74 75define(m4_set_cachesize, [dnl 76Set the size of the database's shared memory buffer pool (that is, the 77cache), to m4_arg(gbytes) gigabytes plus m4_arg(bytes). The cache 78should be the size of the normal working data set of the application, 79with some small amount of additional memory for unusual situations. 80(Note: The working set is not the same as the number of simultaneously 81referenced pages, and should be quite a bit larger!) 82 83m4_p([dnl 84The default cache size is 256KB, and may not be specified as less than 8520KB. Any cache size less than 500MB is automatically increased by 25% 86to account for buffer pool overhead; cache sizes larger than 500MB are 87used as specified.]) 88 89m4_p([dnl 90It is possible to specify caches to m4_db that are large enough so that 91they cannot be allocated contiguously on some architectures; for example, 92some releases of Solaris limit the amount of memory that may be 93allocated contiguously by a process. If m4_arg(ncache) is 0 or 1, the 94cache will be allocated contiguously in memory. If it is greater than 951, the cache will be broken up into m4_arg(ncache) equally sized 96separate pieces of memory.]) 97 98m4_p([dnl 99For information on tuning the m4_db cache size, see 100m4_link(M4RELDIR/ref/am_conf/cachesize, [Selecting a cache size]).])]) 101 102dnl m4_tcl_errfile 103dnl #1: if db or environment. 104define(m4_tcl_errfile, [m4_p([dnl 105When an error occurs in the m4_db library, a m4_db error or an error 106return value is returned by the function. In some cases, however, the 107errno value may be insufficient to completely describe the cause of the 108error especially during initial application debugging.]) 109m4_p([dnl 110The m4_arg(-errfile) argument is used to enhance the mechanism for 111reporting error messages to the application by specifying a file to be 112used for displaying additional m4_db error messages. In some cases, when 113an error occurs, m4_db will output an additional error message to the 114specified file reference.]) 115m4_p([dnl 116ifelse($1, db, [dnl 117The error message will consist of a Tcl command name and a colon (":"), 118an error string, and a trailing m4_htmlquote(newline) character. If 119the database was opened in an environment, the Tcl command name will be 120the environment name (for example, env0), otherwise it will be the 121database command name (for example, db0).],[dnl The error message will 122consist of the environment command name (for example, env0) and a colon 123(":"), an error string, and a trailing m4_htmlquote(newline) 124character.])]) 125m4_p([dnl 126This error-logging enhancement does not slow performance or significantly 127increase application size, and may be run during normal operation as well 128as during application debugging.])]) 129 130define(m4_tcl_environ, [dnl 131m4_tag([-use_environ], [dnl 132The m4_db process' environment may be permitted to specify information 133to be used when naming files; see 134m4_link(M4RELDIR/ref/env/naming, [m4_db File Naming]). 135Because permitting users to specify which files are used can create 136security problems, environment information will be used in file naming 137for all users only if the m4_arg(-use_environ) flag is set.]) 138 139m4_tag([-use_environ_root], [dnl 140The m4_db process' environment may be permitted to specify information 141to be used when naming files; see 142m4_link(M4RELDIR/ref/env/naming, [m4_db File Naming]). 143As permitting users to specify which files are used can create security 144problems, if the m4_arg(-use_environ_root) flag is set, environment 145information will be used for file naming only for users with appropriate 146permissions (for example, users with a user-ID of 0 on m4_posix1_name 147systems).])]) 148 149dnl The mode argument language. 150dnl #1: the subsystem name. 151define(m4_tcl_filemode, [m4_p([dnl 152On UNIX systems, or in m4_posix1_name environments, all files created by $1 153are created with mode m4_arg(mode) (as described in m4_manref(chmod, 2)) and 154modified by the process' umask value at the time of creation (see 155m4_manref(umask, 2)). The group ownership of created files is based on 156the system and directory defaults, and is not further specified by m4_db. 157If m4_arg(mode) is 0, files are created readable and writable by both 158owner and group. On Windows systems, the mode argument is ignored.])]) 159 160dnl Partial put language. 161dnl #1: the command name 162define(m4_tcl_partial_put, [m4_p([dnl 163The m4_arg(dlen) bytes starting m4_arg(doff) bytes from the beginning 164of the specified key's data record are replaced by the data specified 165by the data and size structure elements. If m4_arg(dlen) is smaller 166than the length of the supplied data, the record will grow; if 167m4_arg(dlen) is larger than the length of the supplied data, the record 168will shrink. If the specified bytes do not exist, the record will be 169extended using nul bytes as necessary, and the $1 call will succeed. 170ifelse($1, m4_tcl_db_put, [dnl])]) 171m4_p([dnl 172It is an error to attempt a partial put using the $1 command in a database 173that supports duplicate records. Partial puts in databases supporting 174duplicate records must be done using a m4_tcl_dbc_put command.]) 175m4_p([dnl 176It is an error to attempt a partial put with differing m4_arg(dlen) and 177supplied data length values in Queue or Recno databases with fixed-length 178records.])]) 179