The Migration toolbox provides a number of programs that will help you in migrating Khoros 1.x code to Advanced Khoros 2.2.0.0. See the Migration Manual or the man pages for these routines to find out how to use them. The key programs included in the Migration toolbox are:
kfix updates the source code from Khoros 1.x library calls to Advanced Khoros 2.2.0.0
kfixpane Updates a Khoros 1.x *.pane file to an Advanced Khoros 2.2.0.0 *.pane file
uisupdate Updates a Khoros 1.x *.form file to an Advanced Khoros 2.2.0.0 *.form file
mkproto Creates ANSI prototypes for functions
kdarwin provides a front end to the programs listed above (and others), in order to help evolve a Khoros 1.x program to an Advanced Khoros 2.2.0.0 software object.
The conversion programs available in the Migration toolbox aid in the migration of Khoros 1.x software to Advanced Khoros 2.2.0.0 software, but they cannot do everything; depending on the contents of your Khoros 1.x toolbox, you may have to do more work or less work to upgrade your software. The following summaries give an idea of the migration process for each software object type:
Cantata Workspaces
There is no automatic conversion. You must start Cantata with an empty workspace, and recreate the Khoros 1.x workspace using the Advanced Khoros 2.2.0.0 operator equivalents. The reason for this is that all the operators in Cantata have been rewritten for Advanced Khoros 2.2.0.0; names and arguments have changed so much that a migration script would have been extremely difficult to write, and results would have been uncertain at best. Also, Cantata itself has changed considerably since Khoros 1.x.
Xvroutines
Some automatic conversion is provided. Use uisupdate to convert *.form and *.pane files to an Advanced Khoros 2.2.0.0 version, use the Advanced Khoros 2.2.0.0 software development tools to generate the program framework, and finally, re-code the application by hand. Kfix can help to upgrade Khoros 1.x function calls and bsd/non-POSIX.1 OS calls to their Advanced Khoros 2.2.0.0 equivalent. Since the interface to the GUI and visualization capabilities of Advanced Khoros 2.2.0.0 is so different from that of Khoros 1.x, a migration script would have been extremely difficult to write, and results would have been uncertain at best. Also, the functionality provided by GUI and Visualization is much more comprehensive than that which was provided in Khoros 1.x.
Vroutines
Most of the process can be done with automatic conversion. Use kdarwin to convert the Khoros 1.x vroutine to an Advanced Khoros 2.2.0.0 kroutine. Kdarwin takes Khoros 1.x *.prog and *.pane files, and creates an Advanced Khoros 2.2.0.0 kroutine software object.
Libraries
The amount of automatic conversion possible varies with library contents. If the files are l*.c's from Khoros 1.x vroutines, simply use kdarwin on each vroutine (see above). Otherwise, you must create an empty library software object with the Advanced Khoros 2.2.0.0 Craftsman, and upgrade the code by hand. Kfix can help to move old Khoros 1.x function calls and bsd/non-POSIX.1 OS calls to their Advanced Khoros 2.2.0.0 equivalent.
You will need to run kmigrate (found in the MIGRATION toolbox) for any toolboxes you have developed with an earlier version of Khoros 2 in order to update them to use the improved Imake rules and API changes. In most cases, this will fully update your toolboxes and objects to function in the new system.
You should not run kmigrate on any of the toolboxes provided with the Advanced Khoros 2.2.0.0 release.
It is a good idea to make backup copies of your toolboxes before running kmigrate. If there is a problem with your toolbox that kmigrate can not recover from, you will need your backup copy so that you can fix the problem in the original toolbox and rerun kmigrate.
An example of how to run kmigrate is:
Note: Spaces are not allowed between toolbox names.
Some caveats to migration:
The Big Picture
The format for a KDF file consists of a header, a series of attribute blocks, and a series of data blocks. It can be pictured roughly as follows:
KDF Header Attribute Block for Object Attribute Block for Segment 1 Attribute Block for Segment 2 ... Data Segment 1 Data Segment 2 ...
KDF Header
The KDF header consists of seven bytes followed by two integers. Note that all information contained in a KDF file will be stored in a machine specific format. The seventh byte indicates the machine storage type for the particular file.
4 bytes 2 bytes 1 byte 1 integer 1 integer magic # version # machine type # of data # of attr. sets blocks
The magic number and version number: 01 03 19 94 00 02
The machine type follows the numbers defined in: $BOOTSTRAP/include/machine/kmachine.h
The number of data sets is currently hardwired to 1. This will be used in the future to store multiple data objects per file.
There is always at least one attribute block for storing
the object level attributes. Beyond that, there is one attribute
block for each segment in a data object. The attribute blocks
follow sequentially from the header.
Attribute Blocks
The format for the beginning of an attributes block is:
1 NULL-terminated string 1 integer segment name number of attributes for segment
The segment name will simply be a NULL ('\0') for the object level attribute block. The number of attributes describes the number of user-defined attributes for a segment and may be 0.
If the segment name is NULL, then none of the following information will be present. If the segment name is not NULL, then all the physical segment characteristics will be stored next. The segment characteristics are the dimension, datatype, size, and index order. They are stored as follows:
1 integer 1 NULL-terminated string dimension datatype
dimension integers for size size[0] size[1] ... size[dim-1]
dimension integers for order index order[0] index order[1] ... index order[dim-1]
1 integer 1 integer These should be hardwired to -1 fixed dimension dimension index for now. In the future, these fields will be used for storing multi-resolution data.
Datatypes are stored as a string representation of the datatype. The routine kdefine_to_datatype can be used to convert from the standard Khoros type identifiers to strings and the routine kdatatype_to_define can be used to convert the other direction. (Note: These routines may not be available in Khoros 2.0.2)
Valid datatypes are: bit, byte, unsigned byte, short, unsigned short, integer, unsigned integer, long, unsigned long, float, double, complex, and double complex.
Following this will be all other attributes for this segment. There will be exactly the number of attributes as was indicated at the top of the attribute block. Each attribute will follow the format described in the next section.
attribute 0 attribute 1 ...
Attributes
The format for attributes is:
1 string 1 integer 1 integer 1 string attribute name # of arguments argument size datatype attribute data end of attr. (eoa) tag
The attribute name is a string corresponding to the name of the attribute. The number of attribute arguments and the size of each arguments follow. The datatype of the attribute is stored next. Datatypes are stored in a string. The routine kdefine_to_datatype can be used to convert from the standard khoros type identifiers to strings and the routine kdatatype_to_define can be used to convert the other direction. (Note: These routines may not be available in Khoros 2.0.2)
The valid standard datatypes are: bit, byte, unsigned byte, short, unsigned short, integer, unsigned integer, long, unsigned long, float, double, complex, double complex, and string. Any arbitrarily-defined datatype is also allowed, although it is dependent on the datatype being defined in order to be read.
The attribute data follows, stored in a large contiguous block. The attribute data is followed by an end of attribute (eoa) tag.
The end of attribute tag is a string: "<>" . This tag is only really used when reading past attributes of an unknown data type (an undefined structure datatype for instance).
Data Segments
The data segments are stored following the attribute blocks in a series of blocks with all the data for that particular segment. There is one block per segment. The order of the data segment blocks must match the order of the corresponding attribute blocks.
data segment 1 data segment 2 ...
The amount of data present for each segment must be consistent with the physical segment characteristics specified in the attribute block that corresponds to this segment.
For instance, a segment with the characteristics of dimension = 2, size = [32, 24], and datatype = "byte," dataset would be expecting 32x24 bytes of data to be stored for its segment data block.