convert_forms

Allows a user with DBA privileges to convert legacy file-based forms to storage-based forms. You can manage the conversion process, as follows: Determine whether a given form type or all form types to be converted. Define attribute mapping between the file-based and storage-based forms. Control the conversion process by specifying the number of forms to be converted during each run of the utility. Before performing the conversion, you can run the utility to generate an output file containing the UIDs of the file-based forms. This allows you to formulate a plan for performing the conversion by distributing the workload between multiple runs on multiple machines, if necessary. Run the utility in batch mode without user intervention. Restart the process without data corruption in the event that the process is stopped or terminates abnormally. Generate log files listing information about forms that were successfully converted, failed to convert, and which attribute values are dropped or truncated. These files are retained if the process is terminated before completion. Upgrading forms Updating file-based forms to storage-based forms involves the following steps: Generate a file containing the list of forms to be converted, by running the convert_forms utility, as follows: convert_forms -identify -output_file=file-name [-type=type-name] This produces an output file containing the UIDs of file-based forms, one per line. The output file must be opened in append mode. This allows multiple lists of form type information to be contained in the same file. If the -type argument is not specified, all file-based forms are included in the output file. Run the utility, as required, from one or multiple machines, as follows: convert_forms -convert -process_file=file-name [-input_options=file-name] If errors occur during the conversion process, the UIDs of the forms that were not converted are listed in the error file. After identifying and correcting the errors, you can use the ErrorFile file as the input file when rerunning the utility to convert the forms. The -process_file argument specifies a file containing information that could be specific to each job. The -input_options argument specifies a file that is common to all jobs. Process options file The -process_file argument specifies a file containing information related to specific runs of the utility. You can copy the following example, paste it into a text editor, and use it as a starting point for your process options file: Copy C:\temp\form_uids.txt 1 100000 C:\temp\log.txt C:\temp\error.txt C:\temp\success.txt InputFile Specifies either the file generated as output when the utility is run with the -identify option or the ErrorFile file generated during a conversion run. StartLine The line number in the InputFile that specifies the beginning of the block of forms to be converted. If the line number is not specified, the default value is 1. EndLine The line number in the InputFile file that specifies the end of the block of forms to be converted. If the line number is not specified, the default end line is the end of the file. LogFile Specifies the name of the file that logs information about dropped or truncated attribute values. ErrorFile Specifies the name of the file containing the UIDs of forms that were not converted due to errors. Errors encountered during conversion do not stop the process. When the reasons for the failure have been identified and corrected, the ErrorFile file can be used as the input file when the utility is rerun to convert those forms. SuccessFile Contains UIDs of forms that were successfully converted. This file can be useful for multi-site conversions. All three files, LogFile, ErrorFile, and SuccessFile, are optional. If not specified, the corresponding file is not generated. Input options file Unlike the process options file, which is specific to a particular run of the utility, the file specified by the -input_options argument contains information that is common to all runs of the utility. The following example illustrates the format of an input options file: Copy <Type name=> <DropAttrs action=none | all | unmapped | DropList> <ImanFileAttr name= log=no | yes /> ……………… <Map ImanFileAttr= POMAttr= truncate=no | yes | log /> ………………. <KeepLastModified action=no | yes /> <DeleteImanFile action=yes | no /> ……………….. All element attributes in the file have default values, indicated in italics in the example. If all default values are assumed, the input options file can be omitted. Type One or more Type elements can exist in the mapping file. Forms to be converted can be of different form types, all of which are listed in the file. If a form has no corresponding Type element, all form ImanFile attributes are mapped to the corresponding POM storage class attributes with the same names. DropAttrs Each DropAttrs element can contain zero or more DropList elements. DropAttrs action=none indicates that no attributes are dropped, all indicates that all attributes are dropped and no storage object needs to be created. unmapped indicates that all unmapped attributes are dropped. DropList indicates that a list is created of attributes that are dropped. ImanFileAttr To use the ImanFileAttr element, the DropList action must be used for the DropAttrs element. The ImanFileAttr element has a log attribute. If the value of this attribute is yes, the dropped attribute name and value are written to the log file. MapAttrs Each MapAttrs element can contain one or more Map elements. The Map element allows an ImanFile attribute to be mapped to a POM storage class attribute with a different name. If an ImanFile attribute is not included in this list, it is mapped to the storage class attribute with the same name. The Map element allows you to truncate the string data on conversion. If the truncate attribute value is no an error occurs and the form is not converted. If the value of the truncate attribute is yes, the data is truncated and not logged on the log file, while the log attribute will truncate the data and log it in the log file. Only primitive attribute types are supported by this utility. Date, typed, and untyped references are not supported. Do not create empty storage objects. Create an object only if one or more values are copied from the ImanFile properties. Form attributes are case sensitive. KeepLastModified The KeepLastModified element specifies whether the last modified date must be updated to reflect the time of conversion. The default value is to update the last-modified date. DeleteImanFile The DeleteImanFile element specifies whether to delete the ImanFile after conversion. The default value is to delete the file. You can copy the following example, paste it into a text editor, and use it as a starting point for your input options file: Copy Syntax convert_forms [-u=user-id {-p=password | -pf=password-file} -g=group] -identify -output_file=file-name [-type=form-type] -convert -process_file=file-name [-input_options=file-name] Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. Note If Security Services single sign-on (SSO) is enabled for your server, the -u and -p arguments are authenticated externally through SSO rather than being authenticated against the Teamcenter database. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the password. This argument is mutually exclusive with the -pf argument. -pf Specifies the full path and filename of the password file. For information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -identify Generates an output file containing the UIDs of file-based forms. This argument is used in conjunction with the -output_file argument. -output_file Specifies the name of the output file. -type Specifies the type of the forms to be converted. If not specified, all file-based forms are converted. -convert Converts file-based forms that are read from a previous run of the utility using the-identify option. The -convert argument is used with the -process_file and -input_options arguments. -process_file Specifies the process file containing names of the input file, log file, error file, and success file, as well as the start line number and end line number. For more information about this file, see Process options file. -input_options Specifies the name of an input file containing information about how to convert forms. For more information about this file, see Input options file. This argument is optional. -h Displays help for this utility. Environment As specified in Setting up a Teamcenter command-line environment. Files The convertFormProcessInfo.xsd and convertFormInputOptions.xsd XML schema files are delivered as part of your Teamcenter installation and are located in the imandata directory. You must use these schema files to process the XML files that you generate. Restrictions None. Examples To output the UIDs of all file-based forms of UGPartAttr type into the C:\temp\form_uids.txt file, enter the following command on a single line: Copy convert_forms -u=admin-user -p=admin-password -g=dba -identify -output_file=C:\temp\form_uids.txt -type=UGPartAttr The C:\temp\form_uids.txt file is used in the example in Process options file. To convert file-based forms, reading in the C:\temp\process_info.txt file containing process information and the C:\temp\options_file.txt containing conversion information, enter the following command on a single line: Copy convert_forms -u=admin-user -p=admin-password -g=dba -convert -process_file=C:\temp\process_info.txt -input_options=C:\temp\input_options.txt Related Topics BMIDE for Data Model Design