Technical Bulletin - GT.M V5.4-000A Release Notes

Copyright © 2010 Fidelity Information Services, Inc.  All Rights Reserved. 
 

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.

 

GT.M™ is a trademark of Fidelity Information Services, Inc.  Other trademarks are the property of their respective owners.  

 

This document contains a description of GT.M and the operating instructions pertaining to the various functions that comprise the system. This document does not contain any commitment of FIS.  FIS believes the information in this publication is accurate as of its publication date; such information is subject to change without notice.  FIS is not responsible for any errors or defects. 

Revision History

Version Date Summary
1.6 June 15, 2011 Added more information on S9I08-002695.
1.5 July 14, 2010 Improved the description of C9K01-003225.
1.4 April 5, 2010 Added more information about using GT.M on IBM pSeries AIX.
1.3 March 25, 2010 Added an entry for S9K03-002761.
1.2 March 19, 2010
1.1 February 19, 2010
1.0 February 2, 2010 First published version.

 

GT.M Group

Fidelity Information Services, Inc.

2 West Liberty Boulevard, Suite 300

Malvern, Pennsylvania 19355

United States of America

 

GT.M Support for customers: +1 (610) 578-4226 / gtmsupport@fnis.com

 

Switchboard: +1 (610) 296-8877

Website: http://fis-gtm.com

 

Table of Contents

Click here to go directly to the Changes section.
 
 

Conventions

UNIX: The term UNIX is used here in the general sense of all platforms for which GT.M uses a POSIX API.  As of this date, this includes: AIX; HP-UX on IA64 and PA-RISC; GNU/Linux on IA64, x86 and x86_64; Solaris on SPARC; z/OS.

 

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


Program Names: When referring to a GT.M program or function, the reference is in upper case, e.g, MUPIP BACKUP.  When a specific example is provided, the lower case UNIX command names are used, e.g., mupip backup -database ACN,HIST /backup


Reference Number: 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 or platforms appear in brackets [].


Henceforth, the term "originating instance" is used where previously "primary instance" or "originating primary instance" were used, and the term "replicating instance" is used where previously "secondary instance" and "originating secondary instance" were used.  Since it is easier to change documentation than it is to change software, and given our tradition of maintaining compatibility especially for existing programs and scripts, the former terms will remain in the software for a long time to come, even as they are supplemented with the new terms in the code, and replaced in the documentation.


Return to Table of Contents

Bulletin Overview

GT.M V5.4-000A provides timely remediation of a small number of issues with V5.4-000 (highlighted as V5.4-000A).

 

In V5.4-000A, there is no change in the adaptive (auto-tuning) behavior of the MOREREADTIME deviceparameter introduced in V5.4-000.  However, in this bulletin, we have added an improved description of the "MOREREADTIME" deviceparameter. For more information, see "GT.M Documentation Addendum".  

  

GT.M V5.4-000 adds a major new feature to GT.M, as well as a significant enhancement to operational capability for 24x365 database operation.



There are of course bug fixes, remedied mis-features and smaller enhancements.  For a comprehensive list, see Change History.


Please note: The deprecated "Z" pseudo-transactions (bracketed by ZTSTART / ZTCOMMIT) are not supported in this release.  FIS strongly urges you to remove their use from your code - since they have been deprecated for many years, they are no longer tested and may be removed from GT.M at any time.

 

 

As of the publication date, FIS supports this release on the following hardware and operating system versions.  Contact FIS for a current list of supported platforms.

 

 

Platform

Supported Versions

Notes

Hewlett-Packard Integrity IA64 HP-UX

11V3 (11.31)

 

IA64 GNU/Linux - Red Hat Enterprise Linux

Red Hat Enterprise Linux 5.3

GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.5-24 or later) and ncurses (version 5.5-24 or later).  We have verified that GT.M passes comprehensive testing on RHEL 5.x on machines that have single cells (no more than 8 CPUs).  Multi-cell machines are not considered suitable for production use until they are certified.

Hewlett-Packard PA-RISC HP-UX

11.11

GT.M supports UTF-8 mode and M mode on this platform subject to the following:

 
  • Problems with HP-UX 11.11 prevent FIS from testing 4 byte UTF-8 characters.  FIS understands that the issue is resolved in HP-UX 11.31.  At this time, HP-UX 11.31 is still untested and not formally supported for GT.M; however, we are aware of nothing that would prevent this GT.M release from working correctly on that newer version.


Running GT.M on HP-UX 11i requires that patch PHKL_28475 be applied to the system.  This patch fixes a problem with the lseek64() C library call that GT.M uses.  A system without this patch gives fairly consistent database errors of varying types, structural damage, and in general does not work correctly for any but the most simplistic usage.  The swlist -p command (executed as root) can be used to determine if this patch has been applied.  Since recent "BATCH" and "GOLDEN" patches may contain this patch, your system may already have this patch applied but may not list it separately. Contact your HP support channel for more information.


GT.M does not support database encryption on this platform.

 

GT.M does not support the Memory Mapped (MM) Access Method on this platform.


Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

Hewlett-Packard Alpha/AXP Tru64 UNIX

5.1B

GT.M supports M mode but not UTF-8 mode on this platform.  GT.M does not support database encryption on this platform.


Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

Hewlett-Packard Alpha/AXP OpenVMS

7.3-1/7.3-2/8.2/8.3

GT.M supports M mode but not UTF-8 mode on this platform.  GT.M does not support several recent enhancements on this platform, including but not limited to database encryption, on-line backup, multi-site replication, PIPE devices and triggers.


If you need to work with external calls written in C with Version 6.x of the Compaq C compiler on Alpha OpenVMS, then you must carefully review all the provided kits for that product and apply them appropriately.


Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

IBM System p AIX

5.3, 6.1

Since GT.M processes are 64-bit, FIS expects 64-bit AIX configurations to be preferable.


  • While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.
IBM System z z/OS V1R10 At this time, FIS is not providing a distribution of GT.M for this platform.  Contact your FIS account executive if you need such a distribution.

Sun SPARC Solaris

9 (Update 3 and above) and 10 (Update 6 and above)

GT.M supports the deprecated DAL calls in M mode but not in UTF-8 mode.  Please refer to the Integrating External Routines chapter in the Programmer’s Guide for appropriate alternative solutions.

x86_64 GNU/Linux

Red Hat Enterprise Linux 5.4; Ubuntu 8.04 LTS through 9.10

To run 64-bit GT.M processes requires both a 64-bit kernel as well as 64-bit hardware.

 

GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.5-24 or later) and ncurses (version 5.5 or later).

 

To install GT.M with Unicode (UTF-8) support on RHEL 5.4, in response to the installation question Should an ICU version other than the default be used? (y or n) please respond y and then specify the ICU version (e.g., respond 3.6) to the subsequent prompt Enter ICU version (at least ICU version 3.6 is required. Enter as <minor-ver>.<major-ver>):

x86 GNU/Linux

Red Hat Enterprise Linux 4

This 32-bit version of GT.M runs on either 32- or 64-bit x86 platforms; we expect the X86_64 GNU/Linux version of GT.M to be preferable on 64-bit hardware.

 

GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.3.4-2 or later) and ncurses (version 5.4-1 or later).  The minimum CPU must have the instruction set of a 686 (Pentium Pro) or equivalent. Contact FIS for support of older CPUs.

 

Although RHEL 5.x is officially not supported for the 32-bit x86 GNU/Linux GT.M, we are aware of no reason why GT.M will not run on it.

 

This is the last GT.M release for RHEL 4.x.  Future GT.M releases will require RHEL V5.x.

 

Return to Table of Contents

Migrating to 64-bit platforms

The same application code runs on both 32-bit and 64-bit platforms. Please note that:

 
  • You must compile the application code separately for each platform.  Even though the M source code is exactly the same, the generated object modules are different even on the same hardware architecture - the object code for x86 and x86_64 is different.

  • Parameter-types that interface GT.M with non-M code using C calling conventions must match the data-types on their target platforms.  Mostly, these parameters are for call-ins, external calls, internationalization (collation), and environment translation and are listed in the tables below.  Note that most addresses on 64-bit platforms are 8 bytes long and require 8 byte alignment in structures whereas all addresses on 32-bit platforms are 4 bytes long and require 4-byte alignment in structures.

Call-ins and External Calls

Parameter type

32-Bit

64-bit

Remarks

gtm_long_t

4-byte (32-bit)

8-byte (64-bit)

gtm_long_t is much the same as the C language long type, except on Tru64 UNIX, where GT.M remains a 32-bit application.

gtm_ulong_t

4-byte

8-byte

gtm_ulong_t is much the same as the C language unsigned long type.

gtm_int_t

4-byte

4-byte

gtm_int_t has 32-bit length on all platforms.

gtm_uint_t

4-byte

4-byte

gtm_uint_t has 32-bit length on all platforms

 
  • If your interface uses gtm_long_t or gtm_ulong_t types but your interface code uses int or signed int types, failure to revise the types so they match on a 64-bit platform will cause the code to fail in unpleasant, potentially dangerous and hard to diagnose ways.

Internationalization (Collation)

Parameter type

32-Bit

64-bit

Remarks

gtm_descriptor in gtm_descript.h

4-byte

8-byte

Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

 
  • Assuming other aspects of their code are 64-bit capable, collation routines should require only recompilation.  

Environment Translation 

Parameter type

32-Bit

64-bit

Remarks

gtm_string_t type in gtmxc_types.h

4-byte

8-byte

Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

 
  • Any environment translation routines require only a recompile, assuming other aspects of their code are 64-bit capable.

 

Return to Table of Contents

Recompile

  • Recompile all M and C source files.


 

Return to Table of Contents

Rebuild Shared Libraries or Images

  • Rebuild all Shared Libraries (UNIX) or Shareable Executable Images (OpenVMS) after recompiling all M and C source files.


 

Return to Table of Contents

Additional Installation Instructions 

To install GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.

UNIX

  1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version.  If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version.  FIS suggests installing GT.M V5.4-000A in a Filesystem Hierarchy Standard compliant location such as /usr/lib/fis-gtm/V5.4-000A_arch (for example, /usr/lib/fis-gtm/V5.4-000A_x86) on 32-bit Linux systems.  A location such as /opt/fis-gtm/V5.4-000A_arch would also be appropriate.  Note that the arch suffix is especially important if you plan to install 32- and 64-bit versions of the same release of GT.M on the same system.
  2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

  3. In UNIX editions, make sure gtmsecshr is not running. If gtmsecshr is running, first stop all GT.M processes including the DSE, LKE and MUPIP utilities and then perform kill <pid_of_gtmsecshr>.


  • Never replace the binary image on disk of any executable file while it is in use by an active process.  It may lead to unpredictable results. Depending on the operating system, these results include but are not limited to the denial of service (that is, system lockup) and damage to files that these processes open (that is, database structural damage).
Additional Information for AIX

GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. Before installing GT.M on IBM pSeries AIX, run the following command to check the filesets of this facility: lslpp -l bos.rte.aio


If there are no filesets, then install them from AIX installation media.  Then, use SMIT to configure the Asynchronous IO facility.  Use SMIT as follows:


  • smit aio (for gui mode) or

  • smitty aio (for text mode)

 

For a system that has the "posixaio" option instead of "aio" (also called "legacy aio"), use SMIT as follows:


  • smit posixaio (for gui mode) or

  • smitty posixaio (for text mode)

Select "Configure AIO now".  If you see a message such as "aio0 has been created", it means that there is no further need of setup at this time.

In addition to configuring the aio0 device, select "Change/Show characteristics of Asynchronous I/O" change the value of "State to be configured at system restart" from "defined" to "available".  This ensures that the aio0 device will be available when you next reboot the system.


Since GT.M is not a thread safe application, starting multiple threads in a process, or sometimes even loading libpthreads can cause process failure with symptoms such as SIG-11. On AIX, sometimes seemingly innocuous actions can pull libpthreads into a process and cause it to fail. Two known cases are (a) use of non-POSIX (Olson) names such as America/Chicago for the TZ environment variable - please use POSIX names such as CST6CDT instead - and (b) using LDAP to authenticate userids. Other cases probably exist.


If you expect a database file or journal file to exceed 2GB, then you must configure its file system to permit files larger than 2GB.  Furthermore, should you choose to place journal files on file systems with a 2GB limit, since GT.M journal files can grow to a maximum size of 4GB, you must then set the journal auto switch limit to less than 2 GB.

OpenVMS

To upgrade from a GT.M version prior to V4.3-001, you must update any customized copy of GTM$DEFAULTS to include a definition for GTM$ZDATE_FORM.


You can ignore the following section if you choose the standard GT.M configuration or answer yes to the following question:

Do you want to define GT.M commands to the system


If you define GT.M commands locally with SET COMMAND GTM$DIST:GTMCOMMANDS.CLD in GTMLOGIN.COM or other command file for each process which uses GT.M, you must execute the same command after installing the new version of GT.M before using it.  If you define the GT.M commands to the system other than during the installation of GT.M, you must update the system DCLTABLES with the new GTMCOMMANDS.CLD provided with this version of GT.M.  See the OpenVMS "Command Definition, Librarian, and Message Utilities Manual" section on "Adding a system command."  In both cases, it is important for each process to match the proper GTMCOMMANDS.CLD with the version of GT.M it runs.


Return to Table of Contents

Upgrading to GT.M V5.4-000A

The GT.M database consists of four types of components— database files, journal files, global directories, and replication instance files. The format of each database component may differ for each GT.M version and even for 32-bit/64-bit GT.M platforms on the same hardware architecture.


GT.M upgrade procedure for V5.4-000A consists of 4 stages:  
 

 

Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V5.4-000A depends on your GT.M upgrade history and your current version. 

Stage 1: Upgrading your Global Directory

FIS strongly recommends you make a copy of your Global Directory before upgrading it. There is no way to downgrade a Global Directory to an earlier format.  
 

To upgrade from any prior GT.M version:

 

 
  1. Open your Global Directory with the GDE utility program from GT.M V5.4-000A.
  2. Run the EXIT command. This command automatically, even with no other intervening commands, upgrades the global directory.

 

If you inadvertently open a global directory in an earlier format, with no intention of upgrading it, execute the QUIT command rather than the EXIT command.

 

If you inadvertently upgrade a global directory, perform the following steps:
 
  1. Open the global directory with GDE from V5.4-000A.
  2. Execute the SHOW ALL command.
 
Note: Create a GDE command script, or manually enter the GDE commands corresponding to the output, into GDE from the prior GT.M version.

 

Note: As global directories are binary files, analogous to object files, FIS recommends that you use a GDE command script to create your global directories.

Stage 2: Upgrading your Database Files  

You need to upgrade your database files only when there is a block format upgrade (such as V4->V5). However, some versions, for example, the ones which have been initially been created with V4 (and subsequently upgraded to a V5 format) may additionally need a MUPIP REORG –UPGRADE operation to upgrade previously used but free blocks that may have been missed by earlier upgrade tools. 

 

 

To upgrade from a GT.M version prior to V5.000:

 

 

  1. Upgrade your database files using in-place or traditional database upgrade procedure depending on your situation. For more information on in-place/traditional database upgrade, see Database Migration Technical Bulletin.
  1. Run the MUPIP REORG –UPGRADE command. This command upgrades all V4 block to V5 format.

 

Note: Databases created with GT.M releases prior to V5.0-000 and upgraded to a V5 format retain a maximum size limit of 64M (67,108,864) blocks.
 
 

To upgrade from GT.M V5.0*/V5.1*/V5.2*/V5.3*:

 

 
No database file upgrade procedure is necessary if you upgrade from GT.M V5.0-000 or later to V5.3-000 or later. However, you may need to run the MUPIP REORG –UPGRADE command to upgrade any previously used but free block that may have been missed during earlier upgrade cycles.  You do not need to run MUPIP REORG –UPGRADE in either of the following situations:
 
 
If you have already run the MUPIP REORG –UPGRADE command in a version prior to V5.3-003, subsequent versions cannot determine whether or not it was done correctly and record warnings in the operator log for running MUPIP REORG -UPGRADE. Therefore, you must either:
 

 

For additional upgrade considerations, see "Database Compatibility Notes".  
 
Database Compatibility Notes

Stage 3: Upgrading your Replication Instance File

If you are running a logical multi-site (LMS) application configuration on a UNIX platform, then you need to recreate the replication instance file using the MUPIP REPLICATE -INSTANCE_CREATE command whenever your upgrade changes GT.M from a 32-bit implementation to a 64-bit implementation (or potentially vice versa on the x86 platform).  If your upgrade does not include a change between a 32- and 64-bit implementation then you do not need to recreate the replication instance file.  For example, on Linux systems, you do not have to recreate the replication instance file if you upgrade from 32-bit pre V5.3-001 to 32-bit V5.3-001/V5.3-001A/V5.3-002/V5.3-003. You have to recreate the replication instance file only for the upgrade scenarios below.

 

Note: When upgrading from a 32-bit GT.M version to a 64-bit GT.M version you always need to recreate the replication instance files.  This includes upgrades from V5.3-000 or prior versions to GT.M V5.3-001 or later on AIX or 64-bit Linux and upgrades from V5.3-001 or prior versions to GT.M V5.3-002 or later on Solaris.  After creating new replication instance files, always start it with the -UPDATERESYNC qualifier.  Using pre-existing instance files (as opposed to creating new instance files) could cause any process that reads the instance file (which includes the source server, receiver server, update process and GT.M processes on an originating instance) to abnormally terminate with errors ranging from REPLINSTSECMTCH to a SIG-11 (which would create a corefile).


In the following three scenarios, your source server process terminates abnormally if you do not recreate the replication instance file:


 

In these cases, shut down all receiver servers on other instances looking for updates from this instance, shut down this instance, recreate the instance file and then restart the receiver server on this instance with the -UPDATERESYNC qualifier. 

 

Note: Without the UPDATERESYNC qualifier, the replicating instance synchronizes with the originating instance using state information from both instances and potentially rolling back information on the replicating instance. The UPDATERESYNC qualifier declares the replicating instance to be in a wholesome state matching some prior (or current) state of the originating instance; it causes MUPIP to update the information in the replication instance file of the originating instance and not modify information currently in the database on the replicating instance.  After this command, the replicating instance catches up to the originating instance starting from its own current state. Use UPDATERESYNC only when you are absolutely certain that the replicating instance database was shut down normally with no errors, or appropriately copied from another instance with no errors.

 

You must always follow the steps in the Multi-Site Replication technical bulletin when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

Stage 4: Upgrading your Journal Files

To upgrade from any prior GT.M version: 

 

 

Important: This is necessary because MUPIP can't use journal files from a release other than its own for RECOVER or ROLLBACK. 
 

Return to Table of Contents

Managing M mode and UTF-8 mode

With International Components for Unicode (ICU) version 3.6 or later installed, GT.M's UTF-8 mode provides support for Unicode (ISO/IEC-10646) character strings on selected platforms.  On a system that does not have ICU 3.6 or later installed, or on other platforms, GT.M only supports M mode.

 

On a system that has ICU installed, GT.M installs support for both M mode and UTF-8 mode, including a utf8 subdirectory of the directory where GT.M is installed.  From the same source file, depending upon the value of the environment variable $gtm_chset, the GT.M compiler generates an object file either for M mode or UTF-8 mode.  GT.M generates a new object file when an object file is older than the source file and was generated with the same setting of $gtm_chset/$ZCHset.  A GT.M process triggers an error if it encounters an object file generated with a different setting of $gtm_chset/$ZCHset than that processes' current value.  

 

Always generate an M object module with a value of $gtm_chset/$ZCHset matching the value processes executing that module will have.  As the GT.M installation itself contains utility programs written in M, their object files also conform to this rule.  In order to use utility programs in both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 versions of object modules exist, the latter in the utf8 subdirectory.  This technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use.  If your installation uses both modes, consider a similar pattern for structuring application object code repositories.

 

GT.M is installed in a parent directory and a utf8 subdirectory as follows:  

 
  • Actual files for GT.M executable programs (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified for installation.

  • Object files for programs written in M (GDE, utilities) have two versions - one compiled with support for Unicode in the utf8 subdirectory, and one compiled without support for Unicode in the parent directory.  Installing GT.M generates both the versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed.

  • The utf8 subdirectory has files called mumps, mupip, dse, lke, and so on, which are relative symbolic links to the executables in the parent directory (for example, mumps is the symbolic link ../mumps).

  • When a shell process sources the shell scripts gtmprofile or gtmcshrc, the behavior is as follows:

    • If $gtm_chset is "m", "M" or undefined, there is no change from the previous GT.M versions to the value of the environment variable $gtmroutines.

    • If $gtm_chset is "UTF-8" (the check is case-insensitive),

       
      • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/lib/fis-gtm/gtm_V5.4-000A_i686, then gtmprofile and gtmcshrc set $gtm_dist to /usr/lib/fis-gtm/gtm_V5.4-000A_i686/utf8).

      • The last element of $gtmroutines is $gtm_dist($gtm_dist/..) so that the source files in the parent directory for utility programs are matched with object files in the utf8 subdirectory. 

         

Compiling ICU on HP PA-RISC HP-UX

Note: All GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or later) accept ICU 3.6 or later.
 
As of this writing (November, 2009), ICU version 3.6 can be compiled on HP PA-RISC HP-UX with the following configuration:
 

 

Version: 11.31 (11iv3)

Compiler: cc HP C/aC++ B3910B A.06.12, aCC HP C/aC++ B3910B A.06.15, GNU Make 3.81

 

Instructions:

 
  1. Ensure that system environment variable $PATH includes the location of all the compilers mentioned above.

  2. Download the source code of ICU (in this example, version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C)

  3. At the shell prompt, execute the following commands:

     
     
    gunzip -d < icu4c-3_6-src.tgz | tar -xf -
    cd icu/source/
    chmod +x runConfigureICU configure install-sh
    runConfigureICU --enable-debug HP-UX/ACC --enable-64bit-libs? --enable-rpath –disable-threads
     
    gmake
     
    gmake check
     
    gmake install
     
  4. Set the environment variable $LD_LIBRARY_PATH to point to the location of ICU.  HP-UX uses the environment variable $LD_LIBRARY_PATH to search for dynamically linked libraries to be loaded.

  5. ICU is now installed in /usr/local.

 
  • By default, ICU is installed in /usr/local.  If you install ICU in a different directory, type:

    • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs? --enable-rpath –disable-threads
    • Then execute the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.

 
Note: Although GT.M uses ICU, ICU is not FIS software and FIS does not support ICU.  Instructions for installing and configuring ICU are merely provided as a convenience to you.

Compiling ICU on HP Integrity IA64 HP-UX

Note: All GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or above) accept ICU 3.6 or later.

 

As of this writing (November, 2009), ICU version 3.6 can be compiled on HP Integrity IA64 HP-UX with the following configuration:

 
Version: HP-UX 11.31
Compilers: HP C/aC++ B3910B A.06.15, GNU make (3.81)
Instructions:
 
  1. Ensure that system environment variable PATH includes the location of all the compilers mentioned above.
  2. Download the source code of ICU (in this example version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C).
  3. At the shell prompt, run the following commands:

               gunzip -d<  icu4c-3_6-src.tgz | tar -xf -

            cd icu/source/
            chmod +x runConfigureICU configure install-sh
            runConfigureICU HP-UX/ACC --disable-threads
            gmake
            gmake check
            gmake install
 
  1. Set the environment variable LD_LIBRARY_PATH to point to the location of ICU. HP-UX uses the environment variable LD_LIBRARY_PATH to search for dynamically linked libraries to be loaded.


ICU is now installed in the /usr/local directory.

 

By default, ICU is installed in /usr/local.  If you install ICU in a different directory, type:

  • runConfigureICU HP-UX/ACC --prefix=<install_path> --disable-threads

  • Then run the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.
  

Note: Although GT.M uses ICU, ICU is not FIS software and FIS does not support ICU.  The instructions for installing and configuring ICU are merely provided as a convenience to you.

 

Return to Table of Contents

Setting the environment variable TERM

The environment variable $TERM must specify a terminfo entry that accurately matches the terminal (or terminal emulator) settings. Refer to the terminfo man pages for more information on the terminal settings of the platform where GT.M needs to run.

 

 

 

GT.M sends keypad_xmit before terminal reads for direct mode and READs (other than READ *) if EDITING is enabled. GT.M sends keypad_local after these terminal reads.

 

Return to Table of Contents

Installing Compression Libraries

If you plan to use the optional compression facility for replication, you must provide the compression library.  The GT.M interface for compression libraries accepts the zlib compression libraries without any need for adaptation.  These libraries are included in many UNIX distributions and are downloadable from the zlib home page.  If you prefer to use other compression libraries, you need to configure or adapt them to provide the same API provided by zlib.  Simple instructions for compiling zlib on a number of platforms follow.  Although GT.M uses zlib, zlib is not FIS software and FIS does not support zlib.  These instructions are merely provided as a convenience to you.


If a package for zlib is available with your operating system, FIS suggests that you use it rather than building your own.


Solaris/cc compiler from Sun Studio:

./configure --shared
make CFLAGS="-KPIC -m64"
 

HP-UX(IA64)/HP C compiler:

./configure --shared
make CFLAGS="+DD64"
 

AIX/XL compiler:

./configure --shared
Add -q64 to the LDFLAGS line of the Makefile
make CFLAGS="-q64"
 

Linux/gcc:

./configure --shared
make CFLAGS="-m64"
 
z/OS:
 
Refer to the steps we used to install zlib on z/OS in the GT.M for z/OS technical bulletin.

By default, GT.M searches for the libz.so shared library (libz.sl on HPUX PA-RISC) in the standard system library directories (for example, /usr/lib, /usr/local/lib, /usr/local/lib64).  If the shared library is installed in a non-standard location, before starting replication, you must ensure that the environment variable $LIBPATH (AIX and z/OS) and $LD_LIBRARY_PATH (other UNIX platforms) includes the directory containung the library.  The source and receiver server link the shared library at runtime.  If this fails for any reason (such as file not found, or insufficient authorization), the replication logic logs a DLLNOOPEN error and continues with no compression.


Change History 

V5.4-000A

Fixes and enhancements specific to V5.4-000A are: 

 

S9K03-002761 Using buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting.
S9D10-002376 Checking for defined variables and empty strings in local variable subscripts now conforms to the M standard.
S9K02-002754 Prevent GDE from losing maximum length NAME entries.
S9K02-002755 $QUIT on x86 and x86-64 GNU/Linux returns a uniformly appropriate result.
S9K02-002756 Prevents a process from hanging (or failing) on a compilation error in a line longer than 1023 characters.
S9K02-002757 Better clean up orphaned snapshot files from an INTEG that terminates abnormally.
S9K03-002759 VIEW "NOLVLULLSUBS", "NOUNDEF" combination correctly issues an error for a SET using an undefined local variable as a subscript.
C9K02-002758 During installation correctly set setuid bit for the gtmsecshr wrapper and appropriate permission settings for GDE help in utf-8 mode.
C9H10-002920 Prevent error for blanks lines in a GDE command file and correctly resume an interrupted (<CTRL-C>) command file.
C9J07-003156 Replication source server improvements for database files in WAS_ON replication state.
C9K02-003239 Prevent a rare SIG-11 that occurs when MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE run concurrently with M transaction processing.

 

V5.4-000

Fixes and enhancements specific to V5.4-000 are:


S9C11-002251 Error in place of GTMASSERT for full LOCK_SPACE
S9D08-002354 Error from $GET() when 2nd argument is undefined local variable
S9I08-002695 New Trigger facility
S9I09-002699 No more inappropriate error from VIEW "FLUSH" or "JNLWAIT"
S9J07-002732 Adaptive MOREREADTIME for SOCKET device
S9J07-002737 More user-friendly UNIX distribution kit
S9J11-002749 Cleanup of OPEN for [UNIX] PIPE device
C9902-000839 ONLINE option now usual default for [UNIX] MUPIP INTEG
C9B12-001842 MUPIP INTEG TN_RESET leaves proper state for BACKUP BYTESTREAM
C9D07-002356 SOCKET CONNECT improvements
C9D08-002390 Facility to trigger UNIX diagnostics on processes holding scarce resources
C9E02-002513 TRUNCATE for sequential files corrected for Linux
C9F07-002746 $INCREMENT() now starts with a numeric value when adding a string to an undefined global variable
C9H06-002868 SOCKET device waiting to CONNECT now responds to MUPIP INTRPT
C9H07-002875 UNIX call-in protects against multiple gtm_init or gtm_exit calls
C9H10-002913 UTF-8 terminal input protected from loss on INTRPT
C9J04-003108 $ECODE and $STATUS() protected from change by INTRPT
C9J04-003110 MUPIP checks journal files for correct ENDIAN
C9J04-003118 Performance improvement for sequential file READ in UTF-8 mode
C9J06-003140 UNIX installation makes files executable only if successful
C9J06-003145 UNIX gtmsecshr protects itself against over-length input in addition to existing wrapper protection
C9J07-003148 ZWRITE of undefined alias variables
C9J08-003166 Improve REPLINSTNOHIST error message
C9J08-003170 Permit z/OS object modules to exceed 32 KB
C9J08-003174 Improve handling of the loading of ICU used by UTF-8 mode
C9J08-003178 Improve error message for UNIX IPC issue after an improper shutdown
C9J08-003179 New ^%XCMD utility to XECUTE shell command line input
C9J09-003188 Improve CLOSE for [UNIX] PIPE device
C9J09-003190 Cleanup gtmcrypt_close memory management in the encryption plug-in interface
C9J09-003195 Improve timing on passive replication server shutdown
C9J09-003197 Easy of use improvements for managing basic GT.M environments
C9J09-003198 UNIX deals with invalid group or owner for files
C9J09-003199 Improvements to UNIX shell interface to protect against over-length input in utility commands
C9J09-003201 UNIX installation deals with missing "bin" user or group
C9J10-003202 Prevent rare cases of DBINVGBL errors
C9J10-003203 Properly maintain $REFERENCE after reverse name-level $ORDER() of a global
C9J10-003208 DSE protects against failure when encountering certain bad data
C9J11-003211 Exclusive KILL behavior within an extrinsic function now controlled by an environment variable
C9J11-003214 Prevent rare cases of an inappropriate TPFAIL GGGG error
C9J12-003215 Improve performance for very large numbers of local variables
C9J12-003217 New QUIT * and SET *$$ to return an alias from an extrinsic function
C9K01-003220 Prevent rare cases of DBKEYORD or DBBADNSUB
C9K01-003222 MUPIP BACKUP ensures instance file synchronized with database
C9K01-003225 Maximum UNIX $STORAGE value of 2GB -1


Return to Table of Contents

M-Database Access


Return to Table of Contents

M-Other Than Database Access

 

Return to Table of Contents

Utilities-MUPIP

 

Return to Table of Contents

Utilities-Other Than MUPIP

 

Error Messages

The new error messages introduced in V5.4-000 are as follows:

 

GVDATAGETFAIL

GVDATAGETFAIL, Global variable DATAGET sub-operation (in KILL function) failed. Failure code: cccc.

 

Run Time Trigger Error: The target node for a KILL operation could not present its state to the trigger logic due to a database problem. cccc contains the failure codes for the failed attempts. The database may have integrity errors or the process-private data structures may be corrupted.

 

Action: Report this database error to the group responsible for database integrity at your operation.  

JNLENDIANBIG

JNLENDIANBIG, Journal file jjjj is BIG endian on a LITTLE endian system

  
MUPIP Error: The MUPIP command on a little endian system specified journal file jjjj which was created on a big endian system. GT.M does not convert journal files with incompatible byte ordering.
  
Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

JNLENDIANLITTLE

JNLENDIANLITTLE, Journal file jjjj is LITTLE endian on a BIG endian system

  
MUPIP Error: The MUPIP command on a big endian system specified journal file jjjj which was created on a little endian system. GT.M does not convert journal files with incompatible byte ordering.
  
Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

MAXSSREACHED

MAXSSREACHED, Maximum snapshots - mmmm - for region rrrr reached. Please wait for the existing snapshots to complete before starting a new one.

  
Mupip error: Starting this snapshot would exceed the maximum number of snapshots.
  
Action: Wait for a currently active process using snapshots to complete or terminate an existing snapshot activity. 

MAXTRIGRNEST

MAXTRIGRNEST, Maximum trigger nesting level LLLL exceeded
 
Run Time Trigger Error: GT.M limits trigger invocation depth to LLLL.
 
Action: If you are sure that you do not have an application code bug or misfeature, reduce the depth of trigger invocation, possibly by consolidating triggers.  

MUJNLDBMISSING 

MUJNLDBMISSING, Journal files for required database dddd missing in the MUPIP JOURNAL command 
 
MUPIP Error: MUPIP JOURNAL processing requires journal files for database dddd in order to perform the requested recovery, but the invoking command did not supply a path for those files.
 
Action: Revise the command to include the appropriate journal specification(s) and reissue it.

NOZTRAPINTRIG  

NOZTRAPINTRIG, Use of $ZTRAP in a database trigger environment ($ZTLEVEL greater than 0) is not supported.

Run Time Trigger Error: GT.M requires the use of $ETRAP for error handling within trigger logic.

Action: Modify the application code to use $ETRAP to handle errors in trigger logic.

PROCTERM

PROCTERM, uuuu process termination due to cccc from eeee

Utility Warning: A utility uuuu, typically MUPIP, executing application code, possibly from a trigger, encountered a command cccc to terminate at $zposition location pppp.

Action: It is not typically wholesome for MUPIP to terminate this way - review your error handling and trigger definitions for a possible bug or misfeature.

QUITALSINV

QUITALSINV, QUIT * return when the extrinsic was not invoked with SET *

Run Time Error: A [sub-]routine tried to pass an alias back to the caller, but the routine was not invoked to accept an alias return.

Action: Rework either the invocation or the return, or troubleshoot why the inappropriate invocation occurred. If the routine should conditionally return an alias, use $QUIT to select the proper type of return. 

REGSSFAIL

REGSSFAIL, Process pppp encountered error contributing to the snapshot for region rrrr - the snapshot is no longer valid
  
Mupip error: A GT.M process while trying to write a block to the snapshot failed due to some reason. The reason should be in the operator log.
  
Action: Examine the operator log for details of the failure and take action, possibly modifying file access characteristics or user roles, to address the problem. 

SETINTRIGONLY

SETINTRIGONLY, ISV iiii cannot be modified outside of the trigger environment
  
Run Time Trigger Error: The Intrinsic Special variable iiii can only be SET within the context of trigger logic ($ZTLEVEL > 0)
  
Action: Examine the application logic to determine whether code intended for use in a trigger context falls in an execution path outside of trigger logic. For code intended to execute both inside and outside triggers, use a postcondition that limits the SET to within a trigger. 

SNAPSHOTNOV4

SNAPSHOTNOV4, Cannot downgrade (to V4) while snapshots are in progress. Currently ssss snapshots are in progress for region rrrr.
  
Mupip error: A request to downgrade a region to V4 occurred while a snapshot is in progress.
  
Action: Wait for a currently active process using snapshots to complete before running the downgrade.  Since a downgrade to V4 would not normally be expected, check to verify that the downgrade invocation is appropriate.

SSFILCLNUPFAIL

SSFILCLNUPFAIL, Error while unlinking snapshot file -- xxxx

Mupip error: An attempt to terminate snapshot file maintenance by GT.M updater processes encountered a problem.

Action: Try a MUPIP RUNDOWN. If that has a similar problem, it may be prudent to shut down all access to the database in question in order to stop the burden of maintaining the snapshot file and to ensure it doesn't unnecessarily consume more space. 

SSFILOPERR

SSFILOPERR, Error while doing oooo operation on file ffff
  
Mupip error: The oooo operation on snapshot file ffff failed
  
Action: Analyze the operation and the file characteristics and take appropriate action to clear the problem.  

SSPREMATEOF

SSPREMATEOF, Premature end of file while reading block nnnn of size: bbbb bytes at offset: oooo from zzzz
  
Mupip error: The action attempted access to a block beyond the end of the snapshot file. This means either the process was confused or the file is damaged
  
Action: Retry the action. If the problem persists, contact FIS with information on how to recreate the problem. 

SSSHMCLNUPFAIL

SSSHMCLNUPFAIL, Error while doing snapshot shared memory cleanup. Operation -- ssss. Identifier -- dddd
  
Mupip error: There was an error while doing a snapshot cleanup. The operation ssss indicates what system call failed. The identifier dddd indicates the shared memory identifier that is being cleaned up.
  
Action: Analyze the failure details and take corrective measures. If appropriate carefully clear abandoned resources using the system ipcrm utility. 

SSTMPCREATE

SSTMPCREATE, Cannot create the temporary file in directory dddd for the requested snapshot
  
Mupip error: An action requiring a snapshot file was unable to create it.
  
Action: Verify the directory has appropriate access permissions for the user performing the action. 

SSTMPDIRSTAT

SSTMPDIRSTAT, Cannot access temporary directory dddd
  
Mupip error: An action requiring a snapshot file was unable to access the temporary directory.
  
Action: Verify the directory exists and has appropriate access permissions for the user performing the action. 

SSTMPFILOPEN

SSTMPFILOPEN, Failed to open shadow snapshot file ffff
  
Mupip error: An action requiring a snapshot file was unable to open it.
  
Action: Verify the file exists and has appropriate access permissions for the user performing the action. 

SSV4NOALLOW

SSV4NOALLOW, Database snapshots are supported only on fully upgraded V5 databases. nnnn has V4 format blocks.
  
Mupip error: An action requiring a snapshot was attempted on a database the contains V4 format blocks.
  
Action: Upgrade the database to V5 and re-run the action. 

TRIG2NOTRIG

TRIG2NOTRIG, Sending transaction sequence number xxxx which used triggers to a replicator that does not support triggers
  
MUPIP Warning: The source server encountered a transaction that includes triggers, but its replicating node does not support triggers. Unless you are using application level filters to handle this case, your originating instance and replicating instance are no longer consistent.
  
Action: If this case it not handled by your application level filters, you should either enhance your filters or upgrade the replicating instance to a version of GT.M that supports triggers and load the the appropriate trigger definitions with MUPIP TRIGGER (or $ZTRIGGER()), and then take appropriate action (such as recreating the replicating instance from a backup of the originating instance) to restore consistency.  

TRIGCOMPFAIL

TRIGCOMPFAIL, Compilation of database trigger named tttt failed 
 
Run Time Trigger Error: The -Xecute code of a trigger specification has syntax errors. Because triggers are precompiled when you define them, this error may indicate that either:


Action: Validate the definitions by a SELECT option with MUPIP TRIGGER or $ZTRIGGER(), correct the trigger code syntax and apply a trigger update.  

TRIGINVCHSET

TRIGINVCHSET, Trigger tttt for global gggg was created with CHSET=cccc which is different from the current $ZCHSET of this process
  
Run Time Trigger Error: Trigger tttt on global gggg failed because the process that attempted to update global gggg did not have the same character set that was used to load trigger tttt.  Databases with triggers can only be used by processes that are M mode or UTF-8 mode, depending on the mode of the process that loaded the triggers.

Action: Ensure that processes start with the same character set (as defined by the gtm_chset environment variable) that was used to load the trigger definitions with MUPIP TRIGGER (or $ZTRIGGER() function).

TRIGJNLSTATE

TRIGJNLSTATE, Trigger cannot update journaled database file dddd since triggering update was not journaled

Run Time Trigger Error: A process performed an update on a global in a database region which is not currently journaled, and that update invoked a trigger that, in turn, attempted an update on a global in a database region that is journaled. The secondary GVIS message provides the global name. This would produce a journal state with insufficient information to ensure proper replication of the region with the triggered update.

Action: Revise global directories, journaling characteristics, or trigger logic to prevent this situation.  

TRIGNAMEUNIQ

TRIGNAMEUNIQ, Unable to make trigger name tttt unique beyond vvvv versions already loaded

Run Time Trigger Error: GT.M encountered more than vvvv different instances of the same trigger name across database regions used by the same process.

Action: Revise trigger names to prevent such a high degree of overlap.

TRIGTCOMMIT

TRIGTCOMMIT, TCOMMIT at $ZTLEVEL=LLLL not allowed as corresponding TSTART was done at lower $ZTLEVEL=BBBB

Run Time Trigger Error: A TCOMMIT in trigger logic attempted to complete the active transaction that was started outside of the current trigger. Because trigger actions are atomic with the update initiating them, committing a transaction started prior to or by the triggering update cannot be committed inside the trigger.

Action: Within the trigger context, review the TCOMMIT logic to ensure that it commits only those transactions that are started within the trigger. Ensure that TCOMMIT does not attempt to commit any transaction started prior to or by the triggering update.  

TRIGTLVLCHNG

TRIGTLVLCHNG, Detected a net transaction level ($TLEVEL) change during trigger tttt. Transaction level must be the same at exit as when the trigger started

Run Time Trigger Error: While the trigger logic can use balanced sub-transactions, it cannot cause a net change in $TLEVEL.

Action: Review the transaction management (TSTART, TCOMMIT and TROLLBACK) within trigger logic to ensure that it commits or rolls back any transactions it starts and does not attempt to commit any transaction started prior to, or by, the trigger update. You can use TROLLBACK within trigger logic to block the current transaction, possibly to write error context information. Nonetheless if you use such a TROLLBACK, GT.M subsequently signals this error when you leave the trigger context in order to notify the process that the original triggering update has been discarded.

ZGOTOINVLVL

ZGOTOINVLVL, ZGOTO in a trigger running in mmmm cannot ZGOTO level LLLL

MUPIP Error: A ZGOTO command in trigger logic attempted to specify an inappropriate destination. Currently that is a ZGOTO in a trigger context with a target level of one (1) and an entryref. GT.M does not support such ZGOTO arguments in MUPIP because there is no context outside that of the trigger.

Action: Revise the trigger logic to only use ZGOTO with an entryref within the trigger context of trigger logic. Note that you can ZGOTO out of a trigger, but doing so in MUPIP terminates the MUPIP process. FIS recommends limiting the use of ZGOTO to debugging, error handling and testing. Use of ZGOTO in production code, even for error processing, should always be thoroughly tested.

ZTRIGINVACT

ZTRIGINVACT, Missing or invalid subcode (first) parameter given to $ZTRIGGER()

Run Time Trigger Error: The first argument to $ZTRIGGER() is required to specify its mode of action.

Action: for the first argument of $ZTRIGGER() use an expression that evaluates to "FILE", "ITEM" or "SELECT".

ZTRIGNOTP

ZTRIGNOTP, $ZTRIGGER() cannot use update subcodes FILE or ITEM when a TP transaction is in progress ($TLEVEL greater than zero)

Run Time Trigger Error: A FILE or ITEM operation of $ZTRIGGER() failed because it attempted to apply a trigger definition inside an ongoing transaction. Both FILE and ITEM operations of $ZTRIGGER initiate an implicit transaction to achieve trigger update atomicity, therefore, GT.M does not allow nesting them inside another transaction that potentially might use the very triggers $ZTRIGGER() is attempting to update.

Action: Move all FILE or ITEM operations of $ZTRIGGER() outside the scope of any open transaction.

ZTWORMHOLE2BIG

ZTWORMHOLE2BIG, String length of LLLL bytes exceeds maximum length of mmmm bytes for $ZTWORMHOLE

Run Time Trigger Error: GT.M limits $ZTWORMHOLE length to mmmm bytes and the application attempted to use LLLL bytes.

Action: Restrict the size of the string stored in $ZTWORMHOLE to mmmm bytes. Ensure that $ZTWORMHOLE only holds the information that the application needs during trigger execution. If necessary, reorganize the logic to reduce the amount of local context needed during trigger execution, possibly by using global variables. 


Return to Table of Contents

 
 

GT.M Documentation Addendum

This addendum includes an improved description of SOCKET READ operation and MOREREADTIME deviceparameter. 

SOCKET READ operation

TCP/IP is a stream-based protocol that guarantees that bytes arrive in the order in which they were sent. However, it does not guarantee that they will be grouped in the same packets.

If packets arrive infrequently, or at varying rates that are sometimes slow, a short interval can waste CPU cycles checking for an unlikely event. On the other hand, if the handling of packets is time critical, a long interval can introduce an undesirable latency. If packets arrive in a rapid and constant flow (an unusual situation), the interval doesn't matter as much, as there is always something in the buffer for the READ to work with. If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. For more information on MOREREADTIME, see "MOREREADTIME".

Most SOCKET READ operations terminate as a result of the first condition detected from (a) receipt of delimiters, (b) receipt of the maximum number of characters, or (c) expiration of a timeout.  Note that all of these conditions are optional, and a specific READ may specify zero or more of them.  This document refers to these three conditions as "defined terminating conditions". If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates after it has received at least one character followed by an interval with no new characters. READ also terminates on the receipt of a character that puts the device at its specified WIDTH - you can vary the WIDTH, but it's not optional. An error can also terminate a READ. While none of the terminating conditions is satisfied, the READ continues.
 
The following flowchart represents the logic of a SOCKET READ.   
 



SOCKET READ Termination Conditions

 A SOCKET READ operation terminates if any of the following conditions are met:
 
Terminating Conditions Argument Contains $Device $Key $Test
Error Empty String Error String Empty String 1
Timeout* Data received before timeout Empty String Empty String 0
Delimiter* Data up to, but not including the delimiter Empty String Delimiter String 1
Fixed Length Met*
String of Fixed Length
Empty String Empty String 1
Width
Full width String
Empty String Empty String 1
Buffer Emptied
One (1) to as many characters as provided by the transport interface before waiting for an interval (in milliseconds) specified by MOREREADTIME with no additional input. If MOREREADTIME is not specified, buffer is checked every 200 milliseconds for its first input and then every 10 milliseconds until no new input arrives and no other terminating conditions are met.
IF MOREREADTIME is specified, READ uses that value exclusively for buffer checks.
Empty String Empty String 1
  
* Defined Terminating Conditions  
 

A non-fixed-length read, with no timeout and no delimiters (the sixth row in the above table) requires a complex implementation of sequence of READs to ensure a predictable result. This is because the transport layer stream fragments delivered to the reader has only accidental correspondence with the operations performed by the writer. For example, the following:

 

Write "Message 1","Message 2" is presented to the reader as the stream "Message1Message2" but it can take from one (1) to 18 READ commands to retrieve the entire stream.


Your messaging protocol should implement READ in any of the following ways: 
 
  1. Use a delimiter to separate messages (generic READ and possibly a larger value for MOREREADTIME). 
  1. Specify messages as <length, value> pairs (a pair of fixed-length READs (READ # ) and possibly a larger value for MOREREADTIME).
  2. Parse the bytes or characters as they come in (possibly a smaller value for MOREADTIME) 

MOREREADTIME=intexpr

MOREREADTIME specifies the polling interval (in milliseconds) that a SOCKET device uses to check for arriving packets.

If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. This applies to any SOCKET READ. For more information on implementing SOCKET READ in your application, see "SOCKET READ Operations".

If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates either after it has at least one character followed by an interval with no new packets, or by reaching the specified maximum WIDTH for the SOCKET.

If you use the MOREREADTIME behavior, bear in mind that:
 
 
Return to Table of Contents

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