Along with macOS compatibility — which has been the focus of our efforts since 2004 — version 7.0 adds major new capabilities to Helix for the first time in over ten years.

Some of these changes reflect fundamental differences in the way Classic Mac OS worked compared to current versions of macOS. To support these changes, transformations within the collection structure are required.

For the most part, these changes are automatic. Those that require user intervention — or understanding, at least — are detailed here.

Please take time to read through this technote before upgrading your existing collections to Helix 7.0, so that you are aware of potential issues, and how to avoid them.

With all of these issues, we encourage you to contact technical support if you have any questions or need assistance making the transition to Helix 7.0.

As mentioned above, Helix 7 requires transformations within the collection structure. Once a collection is updated to Helix 7, it can not be opened in Helix 6.x again. For this reason, a new feature of the collection update process offers to automatically make a backup for you. We strongly encourage you to make a backup before updating.

You are reminded of this fact in the Update dialog itself, which includes this paragraph: “Warning: Once your collection is updated, you will not be able to revert to a previous version.” That is followed by a final warning: “This operation can not be reversed.”

Starting in Helix 7.0.2, important changes have been made to address issues with date entry using two-digit years. Two in particular are that default interpretation of a 2-digit year entry is advanced from 1920–2019 to 1950–2049, and that by default, Helix now displays the year in full 4 digit form, for all of the display formats.

For most people this will make little difference, except for places where it may be necessary to widen a data rectangle to display the full 4-digit year. We have developed an applet to help identify and fix these issues, which you can get from the ‘Show Century’ flag in Helix 7.0.2 (and International Resources) technote.

One place where this may require further thinking is in the case where a collection designer has converted a date into text, usually in order to ‘concatenate’ it to other text. This change could cause searches to not find expected records. The ‘Show Century’ flag in Helix 7.0.2 (and International Resources) technote explains the situation in detail and provides links to applets that can help identify whether this issue exists in any given collection. In many cases, the applet can fix the problem as well.

Introduction

Passwords are stored in Helix collections using ‘one-way encryption’ — and there is no known way of reverse-engineering a password to find out what it is. (When you authenticate, the password goes through the same one-way process and authenticates only if the new encryption matches the old one.)

Helix 7.0 brings full Unicode support to Helix, including support for passwords that use Unicode values. This creates an intractable problem for characters whose values change when moving from the old ‘MacRoman’ encoding to Unicode. If the value of a Unicode character does not match the value of that same character in MacRoman* encoding, the password will be rejected, since its (encrypted) value is not the same as the original.

* Although ‘MacRoman’ is used throughout this article, this applies to any Classic Mac text encoding.

The Issue

Fortunately, the value of all ‘standard’ characters is the same in MacRoman and Unicode. The divergence happens for what are known as ‘high-ASCII’ characters. These are characters typed while holding down the option (alt) key.

Because there is no way to figure out what the password is once it is stored in Helix, it is impossible to ‘decode’ an existing password that contains high-ASCII characters in order to convert it to its Unicode equivalent.

Consequently, it is critical that you reset any password that uses high-ASCII characters before updating the collection for Helix 7.0. Failure to do this will make it impossible to authenticate, locking you out of the user (or collection, in the case of a collection password).

Support Applications

Two applets are provided to help with this transition. Test Password For Unicode Compatibility is a stand-alone application that tests a password to determine whether it will continue to work in Helix 7.0. (Those that fail should be changed or removed before updating the collection.) The second one, Reset Passwords is a tool that lets the collection designer (with design mode access) reset multiple passwords in one step. It also checks which users have the Edit Username List… command on a menu, and offers to add it to users of your choosing.

Additional Notes

If a collection is already upgraded, and later it is discovered that some passwords don’t work, there are three options:

1. Open the Edit Username List… dialog (from any user who has it on a menu), choose the username from the list, and assign a new password.
2. Open the collection in Design mode, choose User Password… from the ‘Set’ menu, choose the username from the list, and assign a new password.
3. Send the collection to QSA ToolWorks to have the password reset to ‘no password.’ (Standard USU rates apply.)

If you have any questions about updating passwords for Helix 7.0, contact technical support for assistance.

Helix 7.0 updates text handling from the Classic ‘MacRoman’ text to Unicode, a computing industry standard. Consequently, characters with an ASCII value over 127 (known as ‘high-ASCII’ characters) are no longer valid for use as delimiters for fields, records, or as a start character.

When a collection is updated to Helix 7.0, any view’s I/O delimiter that is greater than 127 is reset to its default value. Those defaults are:

• Start character:  none
• Field delimiter:  Tab (id 9)
• Record delimiter: Linefeed (id 10)

If you want to check your collection for views that will be affected by this change, this script (available on our public scripts page) works with Helix 6.2.4 to identify such views before they are updated.

See the Unicode support technote for more information on this change.

Helix 7.0 restores the color and frame width options from Classic Helix in many places, as well as alternative colors for buttons. Most notable is that data rectangles, group boxes and command rectangles (buttons) remain under the control of macOS on screen, so these properties are typically not supported if macOS does not natively support them.* However, these properties are supported in print, since that is outside the direct control of macOS.

* One exception is button background color, which we have implemented as a transparent color overlay.

If your collection uses these properties — which first appeared in Helix Express 4.0 and went dormant in Helix RADE 6.1 — be sure to read the technotes covering rectangle styles and printing.

If you have any questions about rectangle styles, contact technical support for assistance.

Introduction

The Macintosh operating system has historically used ‘international’ resources (code: itlx) to determine the text encoding used on a user’s computer. These resources — which are limited in scope — are being phased out by Apple, having been replaced by the Unicode standard. (See the Unicode support technote for more information on this important change.)

One of the effects of Apple’s decision is that their old method of encoding non-Roman character sets (e.g. MacJapanese, MacHebrew) is no longer necessary. The Unicode standard includes all of the character sets in a single encoding method, eliminating the need to choose which language’s charaters to use. With Unicode, Japanese, Hebrew and every other major character set in the world are always available.

International Resource itl0 as seen in ResEdit

Preferred Languages System Preference

Potential Issues

Helix 6.2 and earlier use Apple’s itlx resources to determine the text encoding of data in a collection, but these resources no longer provide complete functionality, requiring a change in how Helix 7.0 handles text in a collection.

For most users, this transition will be transparent, but for collections based on non-Roman ‘Mac Encodings,’ guidance is sometimes required to ensure that the conversion to Unicode is done correctly. Our suggestion is to first update a copy of your collection without thinking about these issues. If non-Roman text in your templates and data are correctly converted, you don’t have to do anything more.

If non-Roman text is not converted correctly, read on for an explanation of how Helix attempts to update text, and how you can manually assist it in making the right choice.

Helix 7.0 uses two methods of determining the correct text encoding to use for a collection. First, the “resource region code” from the obsolete itl0 resource is read. (It is circled in the first image on the right.) If the Country number (the name is irrelevant) is found in the chart (at right), the translation is made using macOS “Region” information from the corresponding country. In macOS, regions are specified in the Region popup menu as seen in the final image on the right.

If the collection’s region code is not in that list — and note that regions that use Roman text (including the US!) are not in the list — Helix uses the chosen Preferred language and Region data from the Language & Region System Preference panel, shown at right.

When a collection is updated to Helix 7.0, textual data found in the structure of a collection is converted to Unicode, based on the Mac Encoding set for the collection, if it is found in the chart shown at right. If there is no encoding match, the current Region and Preferred Language settings in the macOS “Language & Region” panel of System Preferences are used.

Updating a collection that uses a non-Roman encoding without first ensuring that the translation can be made will result in text that appears as ‘garbage characters’ in Helix 7.0. This is due to the way the data was stored (‘encoded’) under the now-obsolete ‘Mac Encoding’ system.

Additional Notes

1. Although text in the structure of a collection (static popups, template labels, etc.) is converted to Unicode during the update process, existing record data is not converted to Unicode. Record data is converted only when a field containing Unicode characters is edited. Consequently, if you later switch your system to use a different encoding, you may find that records entered prior to Helix 7.0 are not properly displayed. Switch back to the correct encoding to view them correctly or create posting processes to ‘update’ the existing records. Contact technical support for guidance.
2. For best results, use the most recent version of macOS available when updating collections to Helix 7.0. If you have any difficulty updating a collection, or you require a translation that is not included in the chart, please contact technical support for assistance.
3. Apple has deprecated the itlx resources and — in macOS 10.9 or later only — newly created collections contain US resources. This is expected to be addressed in a future update.
4. Our ability to test the updating of international collections is quite limited, and may be incomplete. Please contact technical support if you encounter any difficulties.
5. See the Unicode support technote for more information on this important change.

If you have any questions about updating international collections, contact technical support for assistance.

Helix 7.0 begins the transition from Apple’s older ‘HFS’ file naming to the current ‘POSIX’ style. One problem users may encounter is with long filenames: Helix 7.0 is limited to filenames of 31 characters or less, including the file type extension. Although older versions of Helix were limited in this same way, they used deprecated routines in macOS that encoded the filename such that the middle of the filename was converted into random characters, and the extension was kept intact. The new routines in macOS simply trim the end off the filename, which can cause a problem if the documents are used with applications that rely on the filename extension to detect the filetype.

The only solution to this problem is to be careful to limit filenames to 31 characters or less, if they are to be managed by Helix 7.0.

The Form Query icon is deprecated. In Helix 7.0, the form query sometimes fails to display all of the the label rectangles on the template. We attempted to fix this, but were unsuccessful. (Obviously.) The limited nature of the form query is such that we can not justify the resources required to maintain it.

A future release will remove the ability to create new form queries, and existing form queries will be converted into power queries. See the using the Power Query in macOS technote for more information.

If you are installing version 7.0.2 or earlier on macOS 10.8 or later, be sure to check the App Nap setting after installing Helix Server. Our home page provides links to the compatibility pages for each version of macOS, where you can find more details regarding App Nap and other compatibility notes.

This issue is resolved in Helix Server 7.0.3, so you can disregard this note if you are installing the latest version of Helix.