Appendix D. Migrating From Previous Versions of Khoros

How do I migrate my Khoros 1.x software to Advanced Khoros 2.2.0.0?

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.

How do I migrate my Khoros 2.0 or 2.1 software to Advanced Khoros 2.2.0.0?

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.


Warning:

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:


> kmigrate -tb <toolbox1>,<toolbox2>,<toolbox3>

Note: Spaces are not allowed between toolbox names.

Some caveats to migration:

KDF Format Specification

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.


Copyright Khoral Research, Inc. 1997; All Rights Reserved