The known limitations of the SoDA 2002.05.00 release are described below. Where possible, work-arounds are also described.
The following limitations apply to all SoDA users.
Cut-and-paste editing operations within and amongst SoDA documents-that is, cutting and pasting that uses FrameMaker+SGML's clipboard-can fail after FrameMaker+SGML has been running for a long time (usually multiple days).
If you encounter this problem, exit SoDA, log out, log in again, and restart SoDA. (You need not reboot your workstation).
Hanging text should be wrapped in a TextRange container where possible. Hanging text is commonly created by the insertion of SoDA elements into the middle of paragraphs:
SoDA provides a utility for wrapping hanging text in a TextRange element. To run this utility on a document, choose the SoDA:Utilities:Wrap Hanging Text menu option. Note that the TextRange element must be defined within your EDD for the conversion to be successful (the SoDA default EDD defines a TextRange element).
Known problems with hanging text include:
For example, if you want to select some portion of hanging text and replace it with a SoDA field, you must instead delete the text and then insert the field at the cursor -position.
SoDA's use of conditional text to hide master elements (that is, elements with replicators attached) precludes the use of conditional text for other purposes within the master elements.
If you do tag text within a master element as conditional, those tags will be removed during document generation and will not appear in the elements added during generation. Once an element has been added, however, condition tags can be applied within it without being deleted by subsequent generations.
If you have a SoDA document with a replicator over some objects, and you regenerate that document with the Delete Mode set to Hide, any elements that were previously generated for objects that have since disappeared will be hidden by the SodaHidden condition tag. Then, if you regenerate the document again, and some of those objects have since reappeared, the corresponding elements will remain hidden because the SodaHidden tag will not be removed from them.
When generating a book or any document in a book, SoDA may encounter various difficulties in opening a document. Such difficulties, which typically cause FrameMaker+SGML to display a dialog box if you try to open the document yourself, include:
If the Ignore .recover and .auto Files toggle button is set on the SoDA Generator dialog box, SoDA opens the (possibly outdated or corrupted) document, displays no message, and continues with document generation. The autosave or recovery file is ignored.
Otherwise, SoDA opens the autosave or recovery file, displays no message, and continues with document -generation. The file is left open after generation so that you can decide how to save it.
SoDA opens the document in View Only format, displays no message, and continues with document generation. SoDA will not be able to generate the view-only document, but it will be able to use the view-only document for generating other documents (which could, for example, depend on global connectors in the view-only document).
Book files cannot be opened in View Only format, so opening a book that already has a lock file will cause an error.
SoDA opens the document despite the missing fonts, displays no message, and continues with document -generation.
SoDA opens the document despite the missing graphics, displays no message, and continues with document -generation.
You can avoid these situations by making sure that you can open all of the documents in your book without difficulty before generating them.
Under FrameMaker+SGML 5.5.6 , Frame *.lck files are not always removed when a document is closed. This is a known issue with FrameMaker+SGML. When the document is re-opened, the Document in Use dialog will be displayed, simply click on Reset Lock and Open to continue editing the document.
If you specify a filename in the "Generate Into" box on HP-UX, you may see a generation report containing the message "The specified file name is invalid". This can occur if you previously generated another (or the same) template as the same target file. If a .lck file exists for the target file from the previous generation, SoDA will not be able to write the document after generation. To work around this problem, manually remove the .lck file prior to generation.
It is possible to define recursive replicators that will cause SoDA to enter an infinite loop when you generate your document. For example, if you recurse down through the file system and encounter a symbolic link that points to a previously traversed parent directory, you will enter an infinite loop. (If you are using SoDA with Rational Apex, the symbolic links named .Rational_Location in Rational Subsystems can cause such loops. Adjust your recursive replicators to avoid them.)
The Unique Only toggle button in the SoDA Replicator dialog box is significant only when there is an expression in the Ordered By area.
If you do not have an insertion point in your document, Check Document will terminate without displaying the expected -consistency report.
You can avoid this problem by clicking in your document, ensuring that you have an insertion point, before choosing Check Document from the SoDA menu.
The Frame domain uses numeric object identifiers in references to Frame document elements. The advantage of this approach is that the referenced document does not need to be modified when the reference is created (whereas standard Frame cross-references, for example, require modification of both the source and referenced documents).
The encoding used by SoDA has been modified to remove the previous limitation preventing conversion to and from Maker Interchange Format (MIF), however the approach still has two disadvantages. Objects are renumbered by:
The effect of object renumbering is that existing replicated document elements linked to renumbered objects will be deleted and re-created when the document is regenerated. If you have added information to these elements, that information will be lost.
Add information to elements replicated from the Frame domain with caution. (The templates delivered with SoDA do not call for any information being added to elements replicated from the Frame domain.)
You can iconify and uniconify documents and books during generation; however, this may occasionally cause a single internal Frame error (usually error -59) if the iconify happens just as an internal Frame call is being issued.
If this error occurs, simply uniconify the document and regenerate the section where the error occurred.
SoDA is not always able to automatically uniconify documents. If you perform an operation on an iconified document, it may not be readily apparent that the operation actually took place.
For example, when visiting a source element that resides in an open, iconified document, the source element will be selected, but the document will remain iconified. -Uniconifying the document will reveal the selected element.
If you bring up and then cancel a SoDA dialog, or if you run the Check Document command from the SoDA menu, your document is marked as having been changed even though it was not.
The following display issues do not affect SoDA functionality, but they do affect its usability to the extent that they can, unfortunately, be a nuisance.
You may notice that documents containing tables flash as the tables are being generated. This flashing does not indicate a problem with the generation.
The structure view is frequently scrolled to the top after SoDA editing operations.
Prior to document or book generation, SoDA closes the structure view to enhance performance. The structure view may be reopened after generation.
During generation of Rose templates, SoDA may display a dialog with the message "FrameMaker lost input focus, recovering". This does not affect the generated document or report. Simply dismiss the dialog, and generation should proceed normally.
Document generation may fail for large documents when full pathnames that access automounted file systems are used. Use relative pathnames when feasible.
The -query option for sodamsg is not supported under HP-UX.
The following limitations apply if you are using SoDA with Rational Apex.
When you do a Control > Check Out All from a book, the checkout command can hang on the Apex side. This problem seems to be caused by command length. Within a book, long pathnames, large numbers of documents, and documents located in other contexts can all lead to the problem.
If you encounter this problem, select the checkout job in the Apex Jobs window and then select Kill from the File menu. This will cause SoDA to return an error, but the documents will be correctly checked out in the CMVC database on the Apex side.
If you have SODA_CMVC_LOCK set to TRUE, SoDA will have locked the documents when they were checked in, and because of the error, will not have unlocked them when they were checked out. Thus, your checked-out documents will still be in FrameMaker+SGML View Only format. When you open them, you can unlock them by entering Esc F l k.
Regardless of the value of the SODA_CMVC_LOCK environment variable, books are not locked because that capability is not currently supported by FrameMaker+SGML.
The following limitations apply if you are using SoDA with -TestMate.
You must have TestMate running to use SoDA's TestMate domain, and your TestMate switches must be set. TestMate will function without the switches, but SoDA's TestMate domain will not.
The following limitations apply if you are using SoDA with Rational Rose.
SoDA supports Rose virtual path maps that start with $, but not those that start with %.
Rose graphics can be exported using an encapsulated postscript format. If you are running SoDA on Solaris 2, or otherwise have display PostScript loaded on your -workstation, the Rose diagrams in your SoDA documents should display correctly on-line.
SoDA is shipped with Ghostscript1, a public domain ("freeware") display utility which enables conversion of the Rose diagrams from EPSF to EPSI. EPSI contains a bitmap that facilitates online display and enables better scaling. Converting the postscript files to EPSI enables SoDA to improve the appearance of graphics in the document, for example by limiting the size of As-Is graphics to the boundaries of the objects it contains. Without Ghostscript, graphics appear with too much white space.
SoDA is shipped and tested with version 2.6.1 of Ghostscript. If you would like to use a different version of Ghostscript, simply set the environment variable SODA_GS_LOCATION to the directory containing your Ghostscript installation prior to starting SoDA.
Note that usage of Ghostscript is subject to the GNU General Public License. A copy of this license is included with the Ghostscript release.
Users using Exceed to run a Unix version of SoDA from a Windows-based personal computer may experience problems importing Rose diagrams into SoDA documents. In most cases, documents may be printed without difficulty even though the graphics may not display correctly. Note that this configuration is not supported by SoDA, users wishing to run from a PC should obtain the latest Windows version of SoDA for Frame, currently 3.1.2.
As of the date of publication, there was an outstanding issue related to the use of SoDA's Rose 2001a and 2002 integrations. Under some circumstances, the Rose application may abort or issue Ole exception errors while SoDA is generating a template. This is usually caused by registry entries which are incompatible with SoDA's Rose client application.
The SoDA-Rose integration is sensitive to the default registry settings, as well as to certain personalized settings you may have in the <user>.reg file in your home directory. Either of the following work-arounds will enable you to reliably generate SoDA templates on HP-UX:
SoDA has been observed to hang for a period of time when querying the Rose domain on HP-UX 10.2 and 11.0 where excessive amount of data are returned. If you observe this scenario, modify the SoDA command (replicator or field) so that less data is returned by the query. SoDA has a limit of 8K bytes returned per query.
The following limitations apply if you are using SoDA with Rational ClearQuest on Unix:
