These are the runtime configuration file variables that are specific to DBMaker. Configuration file variables that are generally applicable to any RDBMS with which Acu4GL communicates. See the Runtime Configuration Variables for more information.
A4GL-COMMIT-COUNT
The value of A4GL-COMMIT-COUNT indicates the conditions under which you want to issue an automatic COMMIT-WORK operation. Valid values are:
1 no automatic commit 0 commit when no locks are held n commit after n file operations (positive values only)Examples
A4GL-COMMIT-COUNT 0
A commit will be issued when no locks are held, either because all files that had locked records have been closed, or because a COBOL COMMIT verb has been issued. This is the default value. Note that some data sources lose the current row when a commit or rollback is executed. For these data sources, a setting of 0 for A4GL-COMMIT-COUNT can adversely affect performance.
A4GL-COMMIT-COUNT n
A commit will be issued after n operations. WRITE, REWRITE and DELETE count towards n; READ, START, and READ NEXT do not.
A4GL-COMMIT-COUNT -1
No commit will be issued by the Acu4GL interface. When COMMIT-COUNT is set to -1, the only way to perform a commit or rollback is to use the COBOL verbs COMMIT and ROLLBACK.
A4GL-COMMIT-COUNT is set to -1 internally when you use the transaction management facilities available in ACUCOBOL-GT.
A COMMIT will, however, be issued on exit from the runtime (for example, on execution of a STOP RUN).
4GL-IGNORED-SUFFIX-LIST
This variable is a space-delimited list of case-independent suffixes to ignore when opening DBMaker Server tables.
By setting this variable (which must be set in the configuration file, and is not settable via SET ENVIRONMENT), the Acu4GL for DBMaker interface will ignore the listed suffixes. There can be up to 10 ignored suffixes (more than that are not kept internally, so will be ignored.) The default value for this variable is "dat".
Example
4GL-IGNORED-SUFFIX-LIST dat idx txt
A-DBM-COMMIT-ON-BEGIN
DBMaker has no START TRANSACTION method. Everything since the last COMMIT or ROLLBACK is considered part of the current transaction.
To ensure that the previous transaction has been ended before a new one begins, set A-DBM-COMMIT-ON-BEGIN to a non-zero value. This causes each COBOL START TRANSACTION to first issue a COMMIT. This ensures that the previous transaction has been ended before the new one starts.
If this variable is not set, or is set to 0, then a COBOL ROLLBACK may affect file I/O that occurred before the most recent COBOL START TRANSACTION. The default value is zero.
A-DBM-DATABASE
Set A-DBM-DATABASE to the exact name of the database that you established in the DBMaker setup. You can set this variable in your COBOL configuration file if you will be using only one database.
For example, if the database you want is:
Testdb
you should add the following line to your configuration file:
A-DBM-DATABASE Testdb
If you do not know the database name in advance, or if you intend to use more than one database, you may set the database name dynamically at runtime. In your COBOL program, you would add code similar to this prior to the statement that opens the file:
SET ENVIRONMENT "A-DBM-DATABASE" TO
"database name"
A-DBM-ERROR-MAP-FILE
In order to allow you to cause specific COBOL errors to be returned due to various DBMaker errors, you may find that database error codes don't necessarily map well to COBOL error codes. To solve this problem, Acu4GL for DBMaker allows you to create an error map file to map native database errors to COBOL errors. Create the file using the guidelines described on the following page, and then use the configuration file variable, A-DBM-ERROR-MAP-FILE, to indicate the name and location of the file you created.
Example
If the file used for mapping is called MAP and this file is located in the directory C:\DBMaker, you would specify:
A-DBM-ERROR-MAP-FILE c:\DBMaker\MAP
in the runtime configuration file. There is no default value for this variable.
Guidelines for Creating Map File
Although you can check your database documentation for error code information, the easiest way to determine what error codes need to be mapped to more appropriate COBOL codes is through trial and error. As users use Acu4GL for DBMaker, they may report receiving error messages that don't make sense based on their situation. Research these errors and try to determine a more appropriate COBOL error response.
When you create your error map file, use the following guidelines:
Using the same example, if you wanted to map the database error, "-346 Could not update a row in the table," to the COBOL error, "Not found," you would include this line in the section:
-346 E_NOT_FOUND
(E indicates errors in ACUCOBOL-GT source code.)
Other error maps would follow in the same section.
The valid values for the second field are as follows:
E_SYS_ERR
E_PARAM_ERR
E_TOO_MANY_FILES
E_MODE_CLASH
E_REC_LOCKED
E_BROKEN
E_DUPLICATE
E_NOT_FOUND
E_UNDEF_RECORD
E_DISK_FULL
E_FILE_LOCKED
E_REC_CHANGED
E_MISMATCH
E_NO_MEMORY
E_MISSING_FILE
E_PERMISSION
E_NO_SUPPORT
E_NO_LOCKS
Through experience, Acucorp has discovered specific ways to better map errors. For a list of these database error mapping suggestions, look at the file dbmaker.err on your installation disks.
A-DBM-LOCK-METHOD
Use this variable to specify the locking method that the interface should use when accessing your data source. Possible values are:
NONE
SETPOS
SETSTMTOPTION
UPDATECOLUMN
Example:
A-DBM-LOCK-METHOD UPDATECOLUMN
The default value is UPDATECOLUMN.
NOTE:
If you really don't want to use record locking, then you can use the value of NONE. This variable describes what the interface does to try to lock records. NONE means that it does nothing special. UPDATECOLUMN means that after a "fetch" (a read of some type) the row is artificially updated (not actually changing any data) in order for the record to be locked. It is at this point that the DBMaker lock logic comes into play. When a record is updated, it is locked until the connection explicitly unlocks it (or a transaction is committed or rolled back.)
Please note that we cannot guarantee that setting this variable will have any effect for a particular DBMaker driver. Locking depends mainly on the data source and the driver. You can use this variable to attempt to induce row locking. If none of the settings cause any rows to be locked, or if the machine hangs, please report this behavior to Acucorp Technical Support.
SETPOS
Specify SETPOS as your lock method to tell Acu4GL for DBMaker to perform the following locking sequence:
1. When setting up a statement handle for accessing the DBMaker data source, the interface calls a function called SQLSetScrollOptions, with values (SQL-CONCUR-LOCK, SQL-SCROLL-KEYSET-DRIVER,1).
2. When fetching rows from the data source, the interface calls SQLExtendedFetch instead of SQLFetch.
3. Finally, it calls SQLSetPos, with the values (1, SQL-POSITION, SQL-LOCK-EXCLUSIVE).
If any of these functions do not exist in the DBMaker driver, then A-DBM-LOCK-METHOD reverts to none.
NOTE:
Even if these functions do exist, there is no guarantee that any rows will be locked using this sequence of calls. Contact your driver vendor to determine whether or not this sequence will be effective for your data source.
SETSTMTOPTION
Specify SETSTMTOPTION as your lock method for DBMaker version 3.0 (and later) drivers. This option is similar to SETPOS except that it has more functionality.
In particular, when using this method of locking, the interface will call SQLSetStmtOption a number of times, with values (SQL-CONCURRENCY, SQL-CONCUR-LOCK), (SQL-CURSOR-TYPES, SQL-CURSOR-KEYSET-DRIVEN), and (SQL_KEYSET-SIZE, 1). Again, if the function does not exist, then A-DBM-LOCK-METHOD reverts to none.
UPDATECOLUMN
Specifying UPDATECOLUMN as your lock method performs an entirely different type of locking. Instead of trying to lock a row while reading it, this method creates a new statement handle for the data source. Then, after fetching the data from the data source, it resubmits an SQL query to select the same row (based on the primary key) and adds an UPDATE clause. Last, it fetches the data from the data source. Because this method has the most overhead, it is not recommended for slow drivers such as Microsoft Access, but it is much more likely to succeed in locking records.
A-DBM-LOGIN
A-DBM-LOGIN indicates the user name under which you want to connect to the database system. Not all databases require a user login name. Those that do may have case requirements.
Example
To connect to the database with the user name MYNAME, you could specify:
A-DBM-LOGIN MYNAME
or
A-DBM-LOGIN myname
in the runtime configuration file. There is no default value for this variable. If no login is specified, none will be used.
See also
A-DBM-PASSWD runtime configuration file variable.
A-DBM-PASSWD
The variable A-DBM-PASSWD should be set to the password assigned to the database account associated with the user name specified by A-DBM-LOGIN.
Examples
If the account with the user name in A-DBM-LOGIN has the associated password CW021535, you would specify:
A-DBM-PASSWD CW021535
in the runtime configuration file.
For better security, you can accept a password from the user during program execution; set the A-DBM-PASSWD variable based on the response:
ACCEPT RESPONSE NO-ECHO.
SET ENVIRONMENT "A-DBM-PASSWD" TO RESPONSE.
Note: If the user has been set up without a password, this variable need not be set. There is no default value for this variable. If no password is specified, none will be used.