------------------------- TO CODAS VERSION 2 USERS: ------------------------- If you have used version 2 of CODAS before, you should take note of the following modifications in version 3: 1. The format of the producer definition file has been changed, as well as the commenting style. See the file \CODAS3\CODAS3.DOC for details on how to set up a new producer definition file. 2. DBADD, DBGET, and DBPUT now require the argument to be an unsigned int containing the number of bytes in the user buffer, rather than the number of elements as in the previous versions of DBADD and DBGET, and none at all in the case of DBPUT. 3. Calling DBGET or DBGET_F with set to zero is interpreted as a query on the database value of , that is, the number of bytes (values in the case of DBGET_F) stored in the database for that particular type. Hence, it results in being updated to this number, rather than causing an error condition, as in the old version. 4. User programs that access the CODAS routines should #include "geninc.h" instead of "dbext.h", "db.dcl", and the more commonly used system #include files. This new #include file takes care of including the usual system #include files as well as the CODAS #include files. Also, the user has to edit only "dbhost.h" in order to set up the host environment parameters, instead of a number of files required by the previous version. 5. The display program \CODAS3\UTIL\SHOWDB.EXE now accepts command line arguments specifying: a. the name of the database to be displayed, b. the name of an external structure definition file, if needed (see \CODAS3\CODAS3.DOC for an explanation of this file), c. a flag indicating whether the structure definitions in the external structure definition file, specified in (b) above, should take precedence over any structure definitions that may already be stored in the CODAS3 block files. The program also shows the structure printing capabilities built into CODAS3. 6. There are three new user routines relating to accessing structure-type variables: a. load_block_strdef Declaration: int load_block_strdef() Returns: 0 if okay, error code otherwise This is used to load structure definitions stored with the block files. The structure definitions define the elements that comprise the structure, and hence permit appropriate access. b. DBLOADSD Declaration: void DBLOADSD(filename, ierr) Arguments: char *filename = address of the name of the external structure definition file int *ierr = address of a variable set to 0 indicating everything worked okay, or to error code indicating what type of error occurred This is used for loading structure definitions from the user's external structure definition file. This is useful for accessing structure-type variables in a CODAS3 database, definitions for which were not loaded at creation time, or which have been updated since. (In the latter case, be careful that those elements whose types have been altered contain values of the appropriate types). Both load_structure_definition() and DBLOADSD() routines should be called only for an open database. DBLOADSD() can be called as many times as there are external structure definition files. The order of calling sets the precedence ordering of the various structure definitions, when they are searched during access. If the user wants the definitions in an external file to take precedence over the block file structure definitions, then his program must call DBLOADSD() with that external file's name as an argument prior to calling load_block_strdef(). The opposite effect can be obtained by reversing the order of the calls. c. DBPRTSTR Declaration: void DBPRTSTR(data, name, nbytes) Arguments: char *data = address of the structure buffer char *name = name of structure unsigned int *nbytes = no. of bytes in data buffer This is used to print structures or arrays of structures. The is used to locate the structure definition in order to print the structure elements in readable fashion; if the structure definition is not located, the structure is printed as an array of unsigned bytes. 7. An error-handling function has been added for more user-friendly error messages: DBERROR Declaration: int void DBERROR(ierr, message) Arguments: int *ierr = pointer to error code char *message = some error message to be displayed if an error occurs Returns: *ierr (0 if no error, <> 0 otherwise) This can be called immediately after any database function call that sets the error code. It checks the error code and prints a brief description of the error, as well as any accompanying message, if the error code is nonzero. 8. There are two other utilities that have been included under the \CODAS3\UTIL subdirectory: a. MKBLKDIR.EXE This utility program was available under version 2 releases for reconstructing the block directory file from a set of block files. The new version additionally features the capability to detect what machine environment the block files were created under, and proceeds to convert them, if necessary, to the host machine environment, while reconstructing the block directory file. The control file for this program has also been modified to feature keywords and to allow specification of external structure definition files that contain definitions for structure-type variables in the block files that may not be available inside the block files (that is, the structure definitions were not loaded at creation time). See the file \CODAS3\UTIL\MKBLKDIR.CNT for an example. b. DB2TODB3.EXE This utility program enables conversion of block files created under CODAS version 2 to a CODAS3 database. It requires a CODAS3 producer definition file as input. If the version 2 database has structure-type variables, then the producer definition file should also provide the required structure definitions. See the file \CODAS3\CODAS3.DOC for details on how to set up the producer definition file. The structure definitions will be automatically loaded as part of the CODAS3 block files. A control file is required to run this program. It specifies the name to be used for the CODAS3 database, the name of the producer definition file, and the names of the CODAS version 2 block files to be converted. 9. The special CODAS printing functions print_ymdhms_time() and print_dmsh_position use a slightly different format. The print_ymdhms_time() function prints the year before the month (the old version put month before year). The print_dmsh_position() function uses different delimiters: ddd' mm" ss.hh (new version) ddd:mm:ss.hh (old version) 10. Primarily as a result of reorganizing the source code into smaller modules, there are several new source files and header files. The more generally useful routines (mostly from the old DB0.C) have been placed into smaller files with their own headers. This allows users to access these routines in isolation, thereby constraining executables to a more manageable size.