GT.M Long Names

Technical Bulletin: GT.M Long Names

Legal Notice

May 03, 2006

Revision History
Revision 1.103 May 2006
Revision 1.06 September 2005



                        



                        GT.M Group

                        Fidelity National Information Services, Inc.

                        2 West Liberty Boulevard, Suite 300

                        Malvern, PA  19355, 

                        United States of America

                     



                        



                        GT.M Support: +1 (610) 578-4226 

                        Switchboard: +1 (610) 296-8877 

                        Fax: +1 (484) 595-5101

                        http://www.fis-gtm.com

                        gtmsupport@fnf.com

                    

Table of Contents

Overview
Special Notes for VMS
GT.M Object File Format Changes
MUPIP Changes
Replication Changes
GT.CM GNP Changes
GDE and Other Utilities
Error Messages
Typographical Conventions

In prior versions, GT.M restricted the length of a valid M name to 8 characters. Effective V5.0-FT01, GT.M allows M names up to thirty one (31) characters long. GT.M ignores any characters after the first 31, i.e. only the first 31 characters are significant in an M name. The following M names are enhanced according to the new length restrictions:

  • Local variables names

  • Global variables names

  • Routine names

  • Source and object file names (not including the extension)

  • Label names

  • Local lock resource names

  • Global lock resource names

For global names, the preceding caret (^) continues to not count towards the limit.

Effective V5.0-FT01, GT.M also enhances region and segment names by allowing up to 31 characters from the existing limit of 16 characters. All GT.M utilities MUPIP, LKE, DSE and GDE including the percent utilities are enhanced according to the new restrictions on M names, region names and segment names.

All M commands and functions that use user-provided identifier names are enhanced to allow up to 31 characters.

Return to top

Special Notes for VMS

On the VMS platform, GT.M previously had a restriction on external routines in that they had to refer to an upper-case M label when calls were made from external routines into M routines. This restriction no longer applies. GT.M allows external routines to call in to mixed-case M labels. In order to call into mixed-case M labels, you need to:

  • Compile the M sources specifying the MUMPS qualifier /LABELS=LOWER so that case-sensitive labels are generated in the object file. Note that this qualifier is enabled by default. Please see the chapter “Program Development Cycle” in the manual “GT.M Programmer’s Guide – VMS Edition” for more details on using the MUMPS /LABELS qualifier.

  • Compile the MACRO file (i.e. call-in table) using the MACRO-64 Assembler specifying the qualifier /NAMES=AS_IS. Please refer to the chapter “Integrating External Routines” in the manual “GT.M Programmer’s Guide – VMS Edition” for more details on using/compiling MACRO tables and the VMS system manual “MACRO-64 Assembler for Open VMS AXP systems” for more details on using the MACRO /NAMES qualifier.

The following are the restrictions with the usage of the MACRO /NAMES qualifier:

  1. GT.M restricts the usage of /NAMES=AS_IS with External Call MACRO tables. Compiling the External Call tables using this option will result in MACRO or LINK errors. Note that GT.M already supports mixed-case M labels for CALLNAME in External Call tables, so this option is not required.

  2. When compiling call-in MACRO tables with /NAMES=AS_IS, ensure that the macro name MUMPS_BINDING as well as the keyword names ENTRYREF, LINKNAME and OUTPUT are used in upper case. If these names are specified in mixed-case, the MACRO table will not compile.

  3. When /NAMES=AS_IS is used, ensure that call-in tables and External Call tables reside in separate MACRO files.

Return to top

GT.M Object File Format Changes

The GT.M object file format has changed because of support up to 31 character long name and reorganizing the internal sections of object files. After the upgrade from an earlier version, all M programs must be recompiled using the new version. GT.M automatically recompiles and replaces old object files. All GT.M shared libraries need to be recreated.

Return to top

MUPIP Changes

The MUPIP binary extract format changed in V5.0-FT01 from the earlier versions. Although binary extract file from V4 releases can be loaded into V5 databases, a V5 binary extract file cannot be loaded into an earlier version database.

Return to top

Replication Changes

In a replicated environment where the primary site is running on V5.0-FT01 or later and the secondary site is running a version prior to V5.0-FT01, the primary will not replicate globals that are longer than 8 characters. The source server detects if the key in the journal record contains a global name of more than 8 characters and exits with the REPLGBL2LONG error.

Return to top

GT.CM GNP Changes

In a client-server environment based on GT.CM GNP protocol, when the client is running V5.0-FT01 or later and the server is running a version prior to V5.0-FT01, any request to access a global with a name longer than 8 characters is blocked at the client. GT.M issues the following error message if the global name has more than 8 characters:

GTM-E-TEXT GT.CM server does not support global names longer than 8 characters.

On the other hand, when the server is running V5.0-FT01 or later and the client is running a version prior to V5.0-FT01, the request from the client would not contain a global name longer than 8 characters, so the operation would be allowed. However, if the result of the operation (i.e. value returned by $ORDER()/$ZPREVIOUS() gives an un-subscripted global variable name) contains a long global name, the server will return the following error to the client:

GTM-I-TEXT GT.CM client does not support global names longer than 8 characters.

Return to top

GDE and Other Utilities

Effective V5.0-FT01, the names of the global variables, database regions and segments used in GDE mapping can be up to 31 characters.

In order to support the longer names in the mapping, the format of the global directory (.gld) files is changed. With the exception of GDE, all GT.M utilities and the run-time system for GT.M processes can only read the new format. They all report version mismatch errors such as GDINVALID if they encounter the global directory (.gld) file in the old format. However, GDE continues to recognize the old format and can read the global directory file successfully. Since GDE automatically converts to the new format, the resultant file, when saved, is always written in the new format.

After installing V5.0-FT01, all global directory (.gld) files created by prior versions must be upgraded using GDE. The upgrade can be performed by setting the environment variable $gtmgbldir [UNIX] or gtm$gbldir [VMS] to the global directory (.gld) file and invoking GDE and then issuing a simple EXIT command to save the file in the new format.

[Note]

Before upgrading a global directory (.gld) file, ensure that a backup copy of the old .gld file is made. GDE does not provide downgrade options to prior versions.

Return to top

Error Messages

GDINVALID

Unrecognized Global Directory file format: "xxx", expected label: "yyy", found: "zzz"

Severity:

Error

Run Time Error:

The version of the global directory file "xxx" (without the quotes) does not match with the version expected by GT.M. The file might have been created by an incompatible GT.M version.

Action:

Compare the labels "yyy" and "zzz" (without the quotes). If the global directory was created by an earlier GT.M version, upgrade the file just by loading and then saving the file using GDE of the new GT.M version.

REPLGBL2LONG

Global names longer than 8 characters cannot be handled at the secondary

Severity:

Error

Source Server Error:

A journal record contains a global variable name longer than 8 characters and the version running at the secondary does not support global variables longer than 8 characters.

Action:

Upgrade the secondary to V5.0-FT01 or later. If upgrade is not possible, avoid replicating regions that contain globals longer than 8 characters.

TEXT

GT.CM server does not support global names longer than 8 characters

Severity:

Error

GT.CM GNP Client Error:

The GT.M GNP client process contains a global variable name longer than 8 characters while the version running at the server does not support global names longer than 8 characters.

Action:

Upgrade the server to V5.0-FT01 or later. If upgrade is not a possible option, avoid using global variable names longer than 8 characters at the client.

TEXT

GT.CM client does not support global names longer than 8 characters

Severity:

Error

GT.CM GNP Server Error:

The result returned by the GT.M GNP server process contains a global variable name longer than 8 characters while the version running at the client does not support global names longer than 8 characters.

Action:

Upgrade the client to V5.0-FT01 or later. If upgrade is not a possible option, avoid using global variable names longer than 8 characters at the server.

Return to top

Typographical Conventions

Command Syntax: UNIX syntax (i.e., lowercase text and "-" for flags/qualifiers) is used throughout this document. VMS accepts both lowercase and uppercase text; flags/qualifiers should be preceded with "/".

Reference Number: The reference numbers used to track software enhancements and customer support requests appear in parentheses ( ).

Platform Identifier: If a new feature or software enhancement does not apply to all platforms, the relevant platform appears in brackets [ ].

Return to top

For more information, see the GT.M web site.