From e13d02a3419bde5ad9e4b5104c5b26d7938ce3e9 Mon Sep 17 00:00:00 2001 From: Marcin Szydelski Date: Apr 28 2019 22:15:24 +0000 Subject: 20190429-00:15 --- diff --git a/applications/infohub/webhelp/common/images/important.html b/applications/infohub/webhelp/common/images/important.html new file mode 100644 index 0000000..3628272 Binary files /dev/null and b/applications/infohub/webhelp/common/images/important.html differ diff --git a/applications/infohub/webhelp/common/images/note.html b/applications/infohub/webhelp/common/images/note.html new file mode 100644 index 0000000..6060a53 Binary files /dev/null and b/applications/infohub/webhelp/common/images/note.html differ diff --git a/applications/infohub/webhelp/common/images/tip.html b/applications/infohub/webhelp/common/images/tip.html new file mode 100644 index 0000000..38a02b0 Binary files /dev/null and b/applications/infohub/webhelp/common/images/tip.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-anim_basic_16x16.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-anim_basic_16x16.html new file mode 100644 index 0000000..77d701a Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-anim_basic_16x16.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_0_aaaaaa_40x100.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_0_aaaaaa_40x100.html new file mode 100644 index 0000000..ce36373 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_0_aaaaaa_40x100.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_55_fbec88_40x100.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_55_fbec88_40x100.html new file mode 100644 index 0000000..0029b7c Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_flat_55_fbec88_40x100.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_75_d0e5f5_1x400.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_75_d0e5f5_1x400.html new file mode 100644 index 0000000..5b1a59b Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_75_d0e5f5_1x400.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_85_dfeffc_1x400.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_85_dfeffc_1x400.html new file mode 100644 index 0000000..69229fc Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_85_dfeffc_1x400.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_95_fef1ec_1x400.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_95_fef1ec_1x400.html new file mode 100644 index 0000000..8753c87 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_glass_95_fef1ec_1x400.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_gloss-wave_55_5c9ccc_500x100.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_gloss-wave_55_5c9ccc_500x100.html new file mode 100644 index 0000000..9a6b960 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_gloss-wave_55_5c9ccc_500x100.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_inset-hard_100_f5f8f9_1x100.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_inset-hard_100_f5f8f9_1x100.html new file mode 100644 index 0000000..5ac575a Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-bg_inset-hard_100_f5f8f9_1x100.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_217bc0_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_217bc0_256x240.html new file mode 100644 index 0000000..cce231d Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_217bc0_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_2e83ff_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_2e83ff_256x240.html new file mode 100644 index 0000000..a746d5c Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_2e83ff_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_469bdd_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_469bdd_256x240.html new file mode 100644 index 0000000..4d3b9a7 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_469bdd_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_6da8d5_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_6da8d5_256x240.html new file mode 100644 index 0000000..33c7bd4 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_6da8d5_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_cd0a0a_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_cd0a0a_256x240.html new file mode 100644 index 0000000..58bf048 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_cd0a0a_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_d8e7f3_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_d8e7f3_256x240.html new file mode 100644 index 0000000..a6ad995 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_d8e7f3_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_f9bd01_256x240.html b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_f9bd01_256x240.html new file mode 100644 index 0000000..2bd20e1 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/theme-redmond/images/ui-icons_f9bd01_256x240.html differ diff --git a/applications/infohub/webhelp/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css b/applications/infohub/webhelp/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css index 0b17363..45a3ffe 100644 --- a/applications/infohub/webhelp/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css +++ b/applications/infohub/webhelp/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css @@ -52,24 +52,24 @@ .ui-widget input, .ui-widget select, .ui-widget textarea, .ui-widget button { font-family: Lucida Grande, Lucida Sans, Arial, sans-serif; font-size: 1em; } .ui-widget-content { border: 1px solid #a6c9e2; background: #fcfdfd url(images/ui-bg_inset-hard_100_fcfdfd_1x100.png) 50% bottom repeat-x; color: #222222; } .ui-widget-content a { color: #222222; } -.ui-widget-header { border: 1px solid #4297d7; background: #5c9ccc url(images/ui-bg_gloss-wave_55_5c9ccc_500x100.png) 50% 50% repeat-x; color: #ffffff; font-weight: bold; } +.ui-widget-header { border: 1px solid #4297d7; background: #5c9ccc url(images/ui-bg_gloss-wave_55_5c9ccc_500x100.html) 50% 50% repeat-x; color: #ffffff; font-weight: bold; } .ui-widget-header a { color: #ffffff; } /* Interaction states ----------------------------------*/ -.ui-state-default, .ui-widget-content .ui-state-default, .ui-widget-header .ui-state-default { border: 1px solid #c5dbec; background: #dfeffc url(images/ui-bg_glass_85_dfeffc_1x400.png) 50% 50% repeat-x; font-weight: bold; color: #2e6e9e; } +.ui-state-default, .ui-widget-content .ui-state-default, .ui-widget-header .ui-state-default { border: 1px solid #c5dbec; background: #dfeffc url(images/ui-bg_glass_85_dfeffc_1x400.html) 50% 50% repeat-x; font-weight: bold; color: #2e6e9e; } .ui-state-default a, .ui-state-default a:link, .ui-state-default a:visited { color: #2e6e9e; text-decoration: none; } -.ui-state-hover, .ui-widget-content .ui-state-hover, .ui-widget-header .ui-state-hover, .ui-state-focus, .ui-widget-content .ui-state-focus, .ui-widget-header .ui-state-focus { border: 1px solid #79b7e7; background: #d0e5f5 url(images/ui-bg_glass_75_d0e5f5_1x400.png) 50% 50% repeat-x; font-weight: bold; color: #1d5987; } +.ui-state-hover, .ui-widget-content .ui-state-hover, .ui-widget-header .ui-state-hover, .ui-state-focus, .ui-widget-content .ui-state-focus, .ui-widget-header .ui-state-focus { border: 1px solid #79b7e7; background: #d0e5f5 url(images/ui-bg_glass_75_d0e5f5_1x400.html) 50% 50% repeat-x; font-weight: bold; color: #1d5987; } .ui-state-hover a, .ui-state-hover a:hover { color: #1d5987; text-decoration: none; } -.ui-state-active, .ui-widget-content .ui-state-active, .ui-widget-header .ui-state-active { border: 1px solid #79b7e7; background: #f5f8f9 url(images/ui-bg_inset-hard_100_f5f8f9_1x100.png) 50% 50% repeat-x; font-weight: bold; color: #e17009; } +.ui-state-active, .ui-widget-content .ui-state-active, .ui-widget-header .ui-state-active { border: 1px solid #79b7e7; background: #f5f8f9 url(images/ui-bg_inset-hard_100_f5f8f9_1x100.html) 50% 50% repeat-x; font-weight: bold; color: #e17009; } .ui-state-active a, .ui-state-active a:link, .ui-state-active a:visited { color: #e17009; text-decoration: none; } .ui-widget :active { outline: none; } /* Interaction Cues ----------------------------------*/ -.ui-state-highlight, .ui-widget-content .ui-state-highlight, .ui-widget-header .ui-state-highlight {border: 1px solid #fad42e; background: #fbec88 url(images/ui-bg_flat_55_fbec88_40x100.png) 50% 50% repeat-x; color: #363636; } +.ui-state-highlight, .ui-widget-content .ui-state-highlight, .ui-widget-header .ui-state-highlight {border: 1px solid #fad42e; background: #fbec88 url(images/ui-bg_flat_55_fbec88_40x100.html) 50% 50% repeat-x; color: #363636; } .ui-state-highlight a, .ui-widget-content .ui-state-highlight a,.ui-widget-header .ui-state-highlight a { color: #363636; } -.ui-state-error, .ui-widget-content .ui-state-error, .ui-widget-header .ui-state-error {border: 1px solid #cd0a0a; background: #fef1ec url(images/ui-bg_glass_95_fef1ec_1x400.png) 50% 50% repeat-x; color: #cd0a0a; } +.ui-state-error, .ui-widget-content .ui-state-error, .ui-widget-header .ui-state-error {border: 1px solid #cd0a0a; background: #fef1ec url(images/ui-bg_glass_95_fef1ec_1x400.html) 50% 50% repeat-x; color: #cd0a0a; } .ui-state-error a, .ui-widget-content .ui-state-error a, .ui-widget-header .ui-state-error a { color: #cd0a0a; } .ui-state-error-text, .ui-widget-content .ui-state-error-text, .ui-widget-header .ui-state-error-text { color: #cd0a0a; } .ui-priority-primary, .ui-widget-content .ui-priority-primary, .ui-widget-header .ui-priority-primary { font-weight: bold; } @@ -80,14 +80,14 @@ ----------------------------------*/ /* states and images */ -.ui-icon { width: 16px; height: 16px; background-image: url(images/ui-icons_469bdd_256x240.png); } -.ui-widget-content .ui-icon {background-image: url(images/ui-icons_469bdd_256x240.png); } -.ui-widget-header .ui-icon {background-image: url(images/ui-icons_d8e7f3_256x240.png); } -.ui-state-default .ui-icon { background-image: url(images/ui-icons_6da8d5_256x240.png); } -.ui-state-hover .ui-icon, .ui-state-focus .ui-icon {background-image: url(images/ui-icons_217bc0_256x240.png); } -.ui-state-active .ui-icon {background-image: url(images/ui-icons_f9bd01_256x240.png); } -.ui-state-highlight .ui-icon {background-image: url(images/ui-icons_2e83ff_256x240.png); } -.ui-state-error .ui-icon, .ui-state-error-text .ui-icon {background-image: url(images/ui-icons_cd0a0a_256x240.png); } +.ui-icon { width: 16px; height: 16px; background-image: url(images/ui-icons_469bdd_256x240.html); } +.ui-widget-content .ui-icon {background-image: url(images/ui-icons_469bdd_256x240.html); } +.ui-widget-header .ui-icon {background-image: url(images/ui-icons_d8e7f3_256x240.html); } +.ui-state-default .ui-icon { background-image: url(images/ui-icons_6da8d5_256x240.html); } +.ui-state-hover .ui-icon, .ui-state-focus .ui-icon {background-image: url(images/ui-icons_217bc0_256x240.html); } +.ui-state-active .ui-icon {background-image: url(images/ui-icons_f9bd01_256x240.html); } +.ui-state-highlight .ui-icon {background-image: url(images/ui-icons_2e83ff_256x240.html); } +.ui-state-error .ui-icon, .ui-state-error-text .ui-icon {background-image: url(images/ui-icons_cd0a0a_256x240.html); } /* positioning */ .ui-icon-carat-1-n { background-position: 0 0; } @@ -282,8 +282,8 @@ .ui-corner-all { -moz-border-radius: 5px; -webkit-border-radius: 5px; border-radius: 5px; } /* Overlays */ -.ui-widget-overlay { background: #aaaaaa url(images/ui-bg_flat_0_aaaaaa_40x100.png) 50% 50% repeat-x; opacity: .30;filter:Alpha(Opacity=30); } -.ui-widget-shadow { margin: -8px 0 0 -8px; padding: 8px; background: #aaaaaa url(images/ui-bg_flat_0_aaaaaa_40x100.png) 50% 50% repeat-x; opacity: .30;filter:Alpha(Opacity=30); -moz-border-radius: 8px; -webkit-border-radius: 8px; border-radius: 8px; }/* Resizable +.ui-widget-overlay { background: #aaaaaa url(images/ui-bg_flat_0_aaaaaa_40x100.html) 50% 50% repeat-x; opacity: .30;filter:Alpha(Opacity=30); } +.ui-widget-shadow { margin: -8px 0 0 -8px; padding: 8px; background: #aaaaaa url(images/ui-bg_flat_0_aaaaaa_40x100.html) 50% 50% repeat-x; opacity: .30;filter:Alpha(Opacity=30); -moz-border-radius: 8px; -webkit-border-radius: 8px; border-radius: 8px; }/* Resizable ----------------------------------*/ .ui-resizable { position: relative;} .ui-resizable-handle { position: absolute;font-size: 0.1px;z-index: 99999; display: block;} @@ -301,7 +301,7 @@ /* Autocomplete ----------------------------------*/ .ui-autocomplete { position: absolute; cursor: default; } -.ui-autocomplete-loading { background: white url('images/ui-anim_basic_16x16.gif') right center no-repeat; } +.ui-autocomplete-loading { background: white url('images/ui-anim_basic_16x16.html') right center no-repeat; } /* workarounds */ * html .ui-autocomplete { width:1px; } /* without this, the menu expands to 100% in IE6 */ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black-line.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black-line.html new file mode 100644 index 0000000..aba20ea Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black-line.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black.html new file mode 100644 index 0000000..acda436 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-black.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default-line.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default-line.html new file mode 100644 index 0000000..d1e670e Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default-line.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default.html new file mode 100644 index 0000000..624dfa8 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-default.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-famfamfam.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-famfamfam.html new file mode 100644 index 0000000..0975625 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-famfamfam.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray-line.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray-line.html new file mode 100644 index 0000000..e0dbf62 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray-line.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray.html new file mode 100644 index 0000000..4d2f124 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-gray.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red-line.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red-line.html new file mode 100644 index 0000000..5b529d1 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red-line.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red.html b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red.html new file mode 100644 index 0000000..edc5729 Binary files /dev/null and b/applications/infohub/webhelp/common/jquery/treeview/images/treeview-red.html differ diff --git a/applications/infohub/webhelp/common/jquery/treeview/jquery.treeview.css b/applications/infohub/webhelp/common/jquery/treeview/jquery.treeview.css index dbf425b..5ffb0d6 100644 --- a/applications/infohub/webhelp/common/jquery/treeview/jquery.treeview.css +++ b/applications/infohub/webhelp/common/jquery/treeview/jquery.treeview.css @@ -10,7 +10,7 @@ } .treeview .hitarea { - background: url(images/treeview-default.gif) -64px -25px no-repeat; + background: url(images/treeview-default.html) -64px -25px no-repeat; height: 16px; width: 16px; margin-left: -16px; @@ -36,29 +36,29 @@ .treeview .hover { color: red; cursor: pointer; } -.treeview li { background: url(images/treeview-default-line.gif) 0 0 no-repeat; } +.treeview li { background: url(images/treeview-default-line.html) 0 0 no-repeat; } .treeview li.collapsable, .treeview li.expandable { background-position: 0 -176px; } .treeview .expandable-hitarea { background-position: -80px -3px; } .treeview li.last { background-position: 0 -1766px } -.treeview li.lastCollapsable, .treeview li.lastExpandable { background-image: url(images/treeview-default.gif); } +.treeview li.lastCollapsable, .treeview li.lastExpandable { background-image: url(images/treeview-default.html); } .treeview li.lastCollapsable { background-position: 0 -111px } .treeview li.lastExpandable { background-position: -32px -67px } .treeview div.lastCollapsable-hitarea, .treeview div.lastExpandable-hitarea { background-position: 0; } -.treeview-red li { background-image: url(images/treeview-red-line.gif); } -.treeview-red .hitarea, .treeview-red li.lastCollapsable, .treeview-red li.lastExpandable { background-image: url(images/treeview-red.gif); } +.treeview-red li { background-image: url(images/treeview-red-line.html); } +.treeview-red .hitarea, .treeview-red li.lastCollapsable, .treeview-red li.lastExpandable { background-image: url(images/treeview-red.html); } -.treeview-black li { background-image: url(images/treeview-black-line.gif); } -.treeview-black .hitarea, .treeview-black li.lastCollapsable, .treeview-black li.lastExpandable { background-image: url(images/treeview-black.gif); } +.treeview-black li { background-image: url(images/treeview-black-line.html); } +.treeview-black .hitarea, .treeview-black li.lastCollapsable, .treeview-black li.lastExpandable { background-image: url(images/treeview-black.html); } -.treeview-gray li { background-image: url(images/treeview-gray-line.gif); } -.treeview-gray .hitarea, .treeview-gray li.lastCollapsable, .treeview-gray li.lastExpandable { background-image: url(images/treeview-gray.gif); } +.treeview-gray li { background-image: url(images/treeview-gray-line.html); } +.treeview-gray .hitarea, .treeview-gray li.lastCollapsable, .treeview-gray li.lastExpandable { background-image: url(images/treeview-gray.html); } .treeview-famfamfam li { background-image: url(images/treeview-famfamfam-line.gif); } -.treeview-famfamfam .hitarea, .treeview-famfamfam li.lastCollapsable, .treeview-famfamfam li.lastExpandable { background-image: url(images/treeview-famfamfam.gif); } +.treeview-famfamfam .hitarea, .treeview-famfamfam li.lastCollapsable, .treeview-famfamfam li.lastExpandable { background-image: url(images/treeview-famfamfam.html); } .filetree li { padding: 3px 0 2px 16px; } diff --git a/applications/infohub/webhelp/content/ch02s01.html b/applications/infohub/webhelp/content/ch02s01.html index 0bf3b33..160847a 100644 --- a/applications/infohub/webhelp/content/ch02s01.html +++ b/applications/infohub/webhelp/content/ch02s01.html @@ -35,10 +35,10 @@ Up | Next

The FIS Information Hub (InfoHub) is a general-purpose application to gather, store, access, and monitor information. It is a "Hub" because it provides a central location for storing current and historical information from multiple environments and from multiple sources in each environment. InfoHub is "general-purpose" because it can be configured for use by tools via SNMP or any connector API for analytics, trending, and reporting. InfoHub is an application written in GT.M, which drives its monitoring framework and provides an n-tuple key-value datastore to hold information. InfoHub includes a ready-to-run Reference Implementation for monitoring GT.M instances that run V6.0-002 or above.

An InfoHub installation contains one or more of:

InfoHubs are general-purpose a?? one InfoHub can monitor multiple data sources, and a single data source can be monitored by multiple InfoHubs. The operations of an InfoHub are data-driven and defined in a text file called InfoHub Configuration File. The InfoHub Configuration File contains a series of descriptors. Descriptors define Publishers that provide information to gather and store in the InfoHub, and Subscriptions for Subscribers to alert based on the information stored in InfoHub. Descriptors also contain information about the environment, sources of data, and the frequency of monitoring (periodic, continuous, or on-demand).

Because it uses character functions for processing external data and only uses byte functions in cases where its internal operation makes them appropriate, an InfoHub can monitor data from sources that rely on ASCII or on various UTF encoding modes. As an application, it can run either in M mode or UTF-8 mode. It does restrict names in its configuration to ASCII, but it can monitor, process and store UTF-8 or UTF16 data.

InfoHub is a GT.M application. Like any other GT.M application, its database can be journaled, recovered, and replicated. An appropriately configured InfoHub using a reference implementation can monitor its own database. InfoHub includes ready-to-run reference implementations: GT.M Monitoring Reference Implementation and Uptime and Log File Monitoring (ULFM) Reference Implementation. For more information on the Reference Implementations available with the InfoHub Distribution, refer to Appendix B: Reference Implementations.

The following illustration is a Reference Implementation of InfoHub for monitoring operator log and WebServer log, and the process output from df and free shell commands. This illustration is only an example to explain a possible InfoHub framework in action. The InfoHub framework setup varies depending on the monitored components and requirements.

- InfoHub monitoring GT.M + InfoHub monitoring GT.M

In this illustration, the white lines represent process controlled connections used for monitoring and the black lines represent the flow of data. The Instance A Publisher uses gleaners to gather data from the system log, WebServer log, and process output from df and free, to store in the InfoHub database.

The relationship between an InfoHub and an Adaptor is of two typesa??Subscriber and Query. The red line represents a Subscriber relationship where the Reporting Adaptor registers itself as a Subscriber with the InfoHub. When data arriving at the InfoHub matches a specified Subscription condition, InfoHub places the data in a queue and sends an interrupt (via a configured GT.M trigger) to the Subscriber. The Subscriber then fetches the data from a queue in the InfoHub database where InfoHub placed it before sending the interrupt. If the Subscriber is the last interested Subscriber, it removes the data from the queue.

The black line represents a Query relationship where the Reporting Adaptor retrieves the requested data from the InfoHub repository . The data flows from the InfoHub to the Subscriber, and the entire flow is managed by the Reporting Adaptor - InfoHub is not aware that the Reporting Adaptor exists.

A single Adaptor can have either one or both relationships with InfoHub. The following illustration demonstrates the relationships between InfoHub and Adaptor(s).

- InfoHub Adaptor relationship -

[Note]Note

InfoHub runs on GT.M V6.0-002 or above. To monitor log files, InfoHub requires the the FOLLOW deviceparameter which was first introduced in V6.0-002. The FOLLOW deviceparameter enables monitoring of sequential disk files that are concurrently being updated by other processes. The GT.M Monitoring Reference Implementation monitors GT.M V6.0-002 using the $ZPEEK() function, which extracts state information from database/journal files. However, using GT.M programming and shell scripting, it is possible to modify that reference implementation to monitor any GT.M version prior to V6.0-002. Required modifications deal with the format and content of file header listings, messages, and gleaning techniques that vary from release to release. For example, to monitor an earlier release which lacks the $ZPEEK() function, you have to use other techniques, such as parsing DSE output, for example, with a program such as the %DSEWRAP utility. However, you do not need to create an alternative functionality for the FOLLOW deviceparameter because it is available within InfoHub as part of the V6.0-002 and can be used for sequential disk files created by any prior GT.M version.

InfoHub is not limited to monitoring GT.M applications. Its ability to gather information and interface with other Reporting Adaptors makes it a useful tool for a broad range of monitoring and alerting needs including (but not limited to):

  • Monitoring of STDERR, STDOUT, STDIN, application and system log files, configuration files, and so on.

  • Monitoring of processes and system resources.

  • Alerting Subscribers based on pre-configured conditions.

  • General-purpose storage and retrieval of time-series data.

PrevA UpA Next
A HomeA
loading table of contents...
PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch03s02.html b/applications/infohub/webhelp/content/ch03s02.html index b4324e1..690b2fe 100644 --- a/applications/infohub/webhelp/content/ch03s02.html +++ b/applications/infohub/webhelp/content/ch03s02.html @@ -34,7 +34,7 @@ | Up | - Next

You can interact with InfoHub from the shell and from within GT.M. To interact with an InfoHub from the shell, the general command is:

$gtm_dist/mumps -run InfoHub --action=<Action> [--<Action_parameters>[=values]...] [--infohub=InfoHubID|InfoHubName] [--gbldir=/path/to/globaldirectory]

To interact with an InfoHub from within GT.M, invoke an entryref like:

<Action>^InfoHub(InfoHubID[,values])
[Tip]InfoHub Internals

^InfoHubConf("GlobalsDirs",$zgbldir) contains the ID of the most recently configured InfoHub.

With a few exceptions, e.g the Actions is "status", "list", or "configure", the underlying mechanism for taking action on an existing InfoHub is to place information in the ^InfoHubActivity global and signal the InfoHubMain service process to invoke its $ZINTERRUPT, which in turn causes it to look in ^InfoHubActivity for instructions on which to act. The action initiating process returns to the operator once it sees an acknowledgement that the InfoHubMain service has taken over the action. Although FIS plans to maintain stability of the published CLI in future releases of InfoHub, without prior notice, FIS may change the underlying mechanism within any InfoHub release.

When starting an InfoHub from the shell command line or from GT.M using the appropriate entryref, the InfoHubMain launches with a JOB command, and control returns to the invoking process once the InfoHub has successfully launched.

[Tip]InfoHub API

More details about the InfoHub API are also documented in the file InfoHub/InfoHub.m. Comments before each entryref describe the input parameters and their types.

PrevA UpA Next
A HomeA

You can interact with InfoHub from the shell and from within GT.M. To interact with an InfoHub from the shell, the general command is:

$gtm_dist/mumps -run InfoHub --action=<Action> [--<Action_parameters>[=values]...] [--infohub=InfoHubID|InfoHubName] [--gbldir=/path/to/globaldirectory]

To interact with an InfoHub from within GT.M, invoke an entryref like:

<Action>^InfoHub(InfoHubID[,values])
[Tip]InfoHub Internals

^InfoHubConf("GlobalsDirs",$zgbldir) contains the ID of the most recently configured InfoHub.

With a few exceptions, e.g the Actions is "status", "list", or "configure", the underlying mechanism for taking action on an existing InfoHub is to place information in the ^InfoHubActivity global and signal the InfoHubMain service process to invoke its $ZINTERRUPT, which in turn causes it to look in ^InfoHubActivity for instructions on which to act. The action initiating process returns to the operator once it sees an acknowledgement that the InfoHubMain service has taken over the action. Although FIS plans to maintain stability of the published CLI in future releases of InfoHub, without prior notice, FIS may change the underlying mechanism within any InfoHub release.

When starting an InfoHub from the shell command line or from GT.M using the appropriate entryref, the InfoHubMain launches with a JOB command, and control returns to the invoking process once the InfoHub has successfully launched.

[Tip]InfoHub API

More details about the InfoHub API are also documented in the file InfoHub/InfoHub.m. Comments before each entryref describe the input parameters and their types.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch03s03.html b/applications/infohub/webhelp/content/ch03s03.html index 3bf14bf..4bd2573 100644 --- a/applications/infohub/webhelp/content/ch03s03.html +++ b/applications/infohub/webhelp/content/ch03s03.html @@ -34,7 +34,7 @@ | Up | - Next

To load a configuration file on an InfoHub from the shell, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=configure --file=<ConfigFileName> [--verbose[=filename]]

Attempting to configure a file that can't be opened for reading, or is defective, produces an IHBADFILE error. Attempting to configure an InfoHub with an improperly installed gtmposix plug-in may produce an IHGETTIMEFAIL error.

To load a configuration file on InfoHub from within GT.M, invoke the following entry point in the InfoHub API as an extrinsic function:

$$configure^InfoHub("InfoHubID","/path/to/ConfigFileName")

If the configuration file contains an InfoHub descriptor, the InfoHubID is optional and, if supplied, must match the one in the descriptor.

[Tip]InfoHub Internals

As IDs, and possibly Names, may have meaning for tools that report on ^InfoHubInfo data, the Infohub configuration processing rejects attempts to change the association between an ID and a Name. A user with sufficient understanding of, and access to, the InfoHub database can change such associations programmatically using GT.M code.

Example:

$ $gtm_dist/mumps -run InfoHub --action=configure --file=samples/SimpleMonitor.conf

This example uses the CLI for InfoHub to load an InfoHub Configuration File. 

GTM>if $$configure^InfoHub("","samples/SimpleMonitor.conf")

This example loads the server1.conf Configuration File on InfoHub. 

GTM>if $$configure^InfoHub("","samples/SimpleMonitor.conf") 
+                                    Next

To load a configuration file on an InfoHub from the shell, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=configure --file=<ConfigFileName> [--verbose[=filename]]

Attempting to configure a file that can't be opened for reading, or is defective, produces an IHBADFILE error. Attempting to configure an InfoHub with an improperly installed gtmposix plug-in may produce an IHGETTIMEFAIL error.

To load a configuration file on InfoHub from within GT.M, invoke the following entry point in the InfoHub API as an extrinsic function:

$$configure^InfoHub("InfoHubID","/path/to/ConfigFileName")

If the configuration file contains an InfoHub descriptor, the InfoHubID is optional and, if supplied, must match the one in the descriptor.

[Tip]InfoHub Internals

As IDs, and possibly Names, may have meaning for tools that report on ^InfoHubInfo data, the Infohub configuration processing rejects attempts to change the association between an ID and a Name. A user with sufficient understanding of, and access to, the InfoHub database can change such associations programmatically using GT.M code.

Example:

$ $gtm_dist/mumps -run InfoHub --action=configure --file=samples/SimpleMonitor.conf

This example uses the CLI for InfoHub to load an InfoHub Configuration File. 

GTM>if $$configure^InfoHub("","samples/SimpleMonitor.conf")

This example loads the server1.conf Configuration File on InfoHub. 

GTM>if $$configure^InfoHub("","samples/SimpleMonitor.conf") 
 Loading the configuration file samples/SimpleMonitor.conf
 GTM>if $$configure^InfoHub("","samples/SimpleMonitor.conf") 
 Loading the configuration file samples/SimpleMonitor.conf 
diff --git a/applications/infohub/webhelp/content/ch03s08.html b/applications/infohub/webhelp/content/ch03s08.html
index a769168..648ca11 100644
--- a/applications/infohub/webhelp/content/ch03s08.html
+++ b/applications/infohub/webhelp/content/ch03s08.html
@@ -34,7 +34,7 @@
                                         |
                                         Up
                                     |
-                                    Next

To pick up a configuration revision and restart an InfoHub, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=restart

To pick up a configuration revision and restart an InfoHub from within GT.M, invoke the following entryref:

restart^InfoHub(InfoHubID|InfoHubName)

This command stops all components whose configuration has changed and starts all components whose configuration has changed (which might not be the same set); attempting to restart of a non-running InfoHub produces an IHNOTRUNNING error.

[Important]Important

The restart command also clears prior restart history for each monitored process. Service monitors will not restart a configuration that fails to start five times within five minutes.

PrevA UpA Next
A HomeA

To pick up a configuration revision and restart an InfoHub, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=restart

To pick up a configuration revision and restart an InfoHub from within GT.M, invoke the following entryref:

restart^InfoHub(InfoHubID|InfoHubName)

This command stops all components whose configuration has changed and starts all components whose configuration has changed (which might not be the same set); attempting to restart of a non-running InfoHub produces an IHNOTRUNNING error.

[Important]Important

The restart command also clears prior restart history for each monitored process. Service monitors will not restart a configuration that fails to start five times within five minutes.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch03s09.html b/applications/infohub/webhelp/content/ch03s09.html index 43cd3ed..bd2035b 100644 --- a/applications/infohub/webhelp/content/ch03s09.html +++ b/applications/infohub/webhelp/content/ch03s09.html @@ -34,7 +34,7 @@ | Up | - Next

To effect a clean InfoHub shutdown from the shell, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=shutdown

To effect a clean InfoHub shutdown from within GT.M, invoke the following entry point in the InfoHub API as an extrinsic function:

$$shutdown^InfoHub(InfoHubID|InfoHubName|^InfoHubConf("GlobalsDirs",$zgbldir))
[Important]Important

Although an InfoHub can be stopped with the MUPIP STOP command, FIS recommends against using MUPIP STOP to shut down an InfoHub because it leaves orphaned service processes.

Example:

$ $gtm_dist/mumps -run InfoHub --action=shutdown

This example shuts down the InfoHub most recently updated using the current global directory. 

GTM>if $$shutdown^InfoHub(7421)

This example shuts down the InfoHub having 7421 as the InfoHub ID.

[Tip]InfoHub Internals

On receipt of a shutdown command (for example, from mumps -run InfoHub --action=shutdown), the InfoHubMain process sends a shutdown message (using the interrupt-based mechanism) to each NoInfo and Publisher process. Each Publisher process in turn sends similar shutdown messages to monitored FileLine and PipeLine processs.

FileLine processs acknowledge receipt, switch their file access mode from FOLLOW to NOFOLLOW with a USE command, continue processing until the end-of-file or Timeout elapses, log their shutdown, and then halt.

For a PipeLine process, the Publisher process sends it "shutdown" message. The PipeLine process sends a "shutdown message" to the PipeCmd process. The PipeCmd process does a READ x:1 at the start of every pass through for data collection. If it reads something as opposed to the 1 second timeout, the sub-process terminates immediately. If the process created by the PipeCmd is a GT.M process, it must READ or WRITE to its principal device in order to detect that PipeLine process has closed the pipe; it should then HALT.

Each Publisher process waits to receive acknowledgement and shutdown completion status from each monitored xLine processes. Only then does it logs its own shutdown, and shuts down. When the InfoHubMain receives acknowledgements from all NoInfo and Publisher processes, it logs its shutdown, and shuts down. The shell command or extrinsic function call then completes.

PrevA UpA Next
A HomeA

To effect a clean InfoHub shutdown from the shell, execute a command like:

$ $gtm_dist/mumps -run InfoHub --action=shutdown

To effect a clean InfoHub shutdown from within GT.M, invoke the following entry point in the InfoHub API as an extrinsic function:

$$shutdown^InfoHub(InfoHubID|InfoHubName|^InfoHubConf("GlobalsDirs",$zgbldir))
[Important]Important

Although an InfoHub can be stopped with the MUPIP STOP command, FIS recommends against using MUPIP STOP to shut down an InfoHub because it leaves orphaned service processes.

Example:

$ $gtm_dist/mumps -run InfoHub --action=shutdown

This example shuts down the InfoHub most recently updated using the current global directory. 

GTM>if $$shutdown^InfoHub(7421)

This example shuts down the InfoHub having 7421 as the InfoHub ID.

[Tip]InfoHub Internals

On receipt of a shutdown command (for example, from mumps -run InfoHub --action=shutdown), the InfoHubMain process sends a shutdown message (using the interrupt-based mechanism) to each NoInfo and Publisher process. Each Publisher process in turn sends similar shutdown messages to monitored FileLine and PipeLine processs.

FileLine processs acknowledge receipt, switch their file access mode from FOLLOW to NOFOLLOW with a USE command, continue processing until the end-of-file or Timeout elapses, log their shutdown, and then halt.

For a PipeLine process, the Publisher process sends it "shutdown" message. The PipeLine process sends a "shutdown message" to the PipeCmd process. The PipeCmd process does a READ x:1 at the start of every pass through for data collection. If it reads something as opposed to the 1 second timeout, the sub-process terminates immediately. If the process created by the PipeCmd is a GT.M process, it must READ or WRITE to its principal device in order to detect that PipeLine process has closed the pipe; it should then HALT.

Each Publisher process waits to receive acknowledgement and shutdown completion status from each monitored xLine processes. Only then does it logs its own shutdown, and shuts down. When the InfoHubMain receives acknowledgements from all NoInfo and Publisher processes, it logs its shutdown, and shuts down. The shell command or extrinsic function call then completes.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch03s11.html b/applications/infohub/webhelp/content/ch03s11.html index c2483d5..1ad9486 100644 --- a/applications/infohub/webhelp/content/ch03s11.html +++ b/applications/infohub/webhelp/content/ch03s11.html @@ -49,7 +49,7 @@ PID [28987] has been notified GTM>
$ $gtm_dist/mumps -r ^InfoHub --action=jobexam --pidlist=28981,28987
 PID [28981] has been notified
 PID [28987] has been notified
-$

Both examples place the output of ZSHOW "*" in a file called infohub-<service>-<infohub id>[-<publisher | noinfo id>[-<xline id>]-<configuration sequence number>.ZSHOW_DMP_"_$JOB_"_"_<cntr> for PIDs 28981 and 28987.

[Important]Important

The ZSHOW "*" output in the JOBEXAMINE files may contain confidential information gleaned from the monitored components that the process holds in local variables, and, possibly, in Intrinsic Special Variables (ISVs). If that is the case in your InfoHub deployment, ensure that the files produced by this command are appropriately secured.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch04s01.html b/applications/infohub/webhelp/content/ch04s01.html index 2200b7d..0753a8d 100644 --- a/applications/infohub/webhelp/content/ch04s01.html +++ b/applications/infohub/webhelp/content/ch04s01.html @@ -36,7 +36,7 @@ | Next

Syntax: - 

InfoHub:[InfoHubName]:[InfoHubID]
[Tip]InfoHub Internals

InfoHubID applies to all elements in a configuration file and is the first subscript for all global variables in the database related to a particular InfoHub, except for the sub-tree that maps global directories to InfoHubIDs using "GlobalsDirs" as the first subscript.

Configuration processing stores InfoHub descriptor information in the following node:

^InfoHubConf(InfoHubID,BeginningSequenceNumber)=a??[EndingTimeStamp]:a??BeginingTimeStamp:a??InfoHubName:a??GldFileName:a??ConfigurationFileName

[Tip]InfoHub Internals

Processing a Configuration File is done using a GT.M LOCK on ^InfoHubConf with InfoHubID as a subscript to ensure only one process is handling a Configuration File for an InfoHub at a given time. If the configuration process detects an another process is holding a lock on this InfoHubID for more than 30 seconds, it produces an IHCONFLOCKED error.

The Verbose option for configuration processing generates substantial output that documents how the processing works. This may be useful for debugging some types of configuration problems. If you have a rich configuration, consider building it up in a series of modest increments to make debugging easier.

Example:

InfoHub:SimpleMonitor:11

This example defines an InfoHub called SimpleMonitor. This example is a part of SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA
loading table of contents...
PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch04s03.html b/applications/infohub/webhelp/content/ch04s03.html index 1133673..4e7a755 100644 --- a/applications/infohub/webhelp/content/ch04s03.html +++ b/applications/infohub/webhelp/content/ch04s03.html @@ -48,7 +48,7 @@ Env:gtmroutines="$gtmroutines /path/to/infohub/M(/path/to/infohub) /path/to/infohub/pipecommands/M(/path/to/infohub/pipecommands) /path/toinfohub/plugins/M(/path/toinfohub/plugins) /path/to/gtmposixplugin/M(/path/to/gtmposixplugin)"

and for the applications using UTF-8 mode:

Env:gtmroutines="$gtmroutines /path/to/infohub/UTF8(/path/to/infohub) /path/to/infohub/pipecommands/UTF8(/path/to/infohub/pipecommands) /path/toinfohub/plugins/UTF8(/path/toinfohub/plugins) /path/to/gtmposixplugin/UTF8(/path/to/gtmposixplugin)" -

Attempting to configure an env descriptor without providing a suitable environment produces an IHBADENV error. Each EnvVarName is a legal POSIX environment variable name, consisting solely of ASCII letters, digits, and underscores ("_"), of which the first character must not be a digit; if configuration processing encounters a failure to meet this criterion, it also produces the IHBADENV error. To allow for permissible, non-graphic values[1] of environment variables, and to allow environment variables to reference environment variables of the InfoHub itself (using the $ZTRNLNM() function), each Value is treated as a GT.M expr that the InfoHub evaluates before storing the result in its database.

[Tip]InfoHub Internals

Configuration processing stores Env descriptor information in the following nodes:

^InfoHubConf(InfoHubID,"EnvSetUp",1,BeginningSequenceNumber)=a??[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that an InfoHub process uses to manage its environment.

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??"EnvSetUp")a??=[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that a Publisher process uses to adjust the environment provided to it by its InfoHub to be appropriate for a PipeLine process.

Expression evaluation (implemented with indirection or XECUTE) also has the potential for side effects that can affect the InfoHub itself. To protect the InfoHub itself from side effects of evaluated expressions, the InfoHub processes Env descriptors in a routine which protects itself by:

  • setting $ZROUTINES to the null string to prevent any new routines from being linked;

  • creating a temporary global directory and database with $ZGBLDIR pointing there;

  • executing an exclusive NEW; and

  • receiving results in $ZTWORMHOLE, it being impossible to modify $ZTWORMHOLE as a side-effect of an expression. ($ZTWORMHOLE can itself be safely saved and restored in the calling routine to retain its originally intended use for triggers.)

Example:

Env:LC_TIME='fr_FR.UTF-8'
+

Attempting to configure an env descriptor without providing a suitable environment produces an IHBADENV error. Each EnvVarName is a legal POSIX environment variable name, consisting solely of ASCII letters, digits, and underscores ("_"), of which the first character must not be a digit; if configuration processing encounters a failure to meet this criterion, it also produces the IHBADENV error. To allow for permissible, non-graphic values[1] of environment variables, and to allow environment variables to reference environment variables of the InfoHub itself (using the $ZTRNLNM() function), each Value is treated as a GT.M expr that the InfoHub evaluates before storing the result in its database.

[Tip]InfoHub Internals

Configuration processing stores Env descriptor information in the following nodes:

^InfoHubConf(InfoHubID,"EnvSetUp",1,BeginningSequenceNumber)=a??[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that an InfoHub process uses to manage its environment.

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??"EnvSetUp")a??=[EndingSquenceNumber]:a??env=[value],..., where the string value of the node is constructed of shell commands that a Publisher process uses to adjust the environment provided to it by its InfoHub to be appropriate for a PipeLine process.

Expression evaluation (implemented with indirection or XECUTE) also has the potential for side effects that can affect the InfoHub itself. To protect the InfoHub itself from side effects of evaluated expressions, the InfoHub processes Env descriptors in a routine which protects itself by:

  • setting $ZROUTINES to the null string to prevent any new routines from being linked;

  • creating a temporary global directory and database with $ZGBLDIR pointing there;

  • executing an exclusive NEW; and

  • receiving results in $ZTWORMHOLE, it being impossible to modify $ZTWORMHOLE as a side-effect of an expression. ($ZTWORMHOLE can itself be safely saved and restored in the calling routine to retain its originally intended use for triggers.)

Example:

Env:LC_TIME='fr_FR.UTF-8'
 Env:LANG='en_US.utf-8'

[1] Quoting from IEEE Std 1003.1-2008: The values that the environment variables may be assigned are not restricted except that they are considered to end with a null byte and the total space used to store the environment and the arguments to the process is limited to {ARG_MAX} bytes.

PrevA UpA Next
A HomeA

The InfoDict [Domain] Descriptor can appear anyplace after the InfoHub Descriptor, except immediately prior to an ENV descriptor, but most logically falls between any InfoHub Environment Descriptors and the Publisher Descriptors. An InfoDict is an organizational container or domain. While InfoDicts are the tool for organizing the schema and behavior of the InfoHub, they do so indirectly, and never appear in the paths of the main storage schema. The syntax of an InfoDict Domain Descriptor is:

InfoDict:InfoDictName:[InfoDictID][:{ParentInfoDictID | ParentInfoDictName}]
[Tip]InfoHub Internals

Configuration processing stores InfoDict domain information in the following nodes:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber)=a??EndingSequenceNumber]:a??InfoDictName

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,0,a??ParentInfoDictID)a??=[EndingSequenceNumber]:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,a??"Children",a??ChildInfoDictID): this node is only maintained for the current configuration of this InfoHub.

Example:

InfoDict:GenericDict::SystemDict
+                                    Next

The InfoDict [Domain] Descriptor can appear anyplace after the InfoHub Descriptor, except immediately prior to an ENV descriptor, but most logically falls between any InfoHub Environment Descriptors and the Publisher Descriptors. An InfoDict is an organizational container or domain. While InfoDicts are the tool for organizing the schema and behavior of the InfoHub, they do so indirectly, and never appear in the paths of the main storage schema. The syntax of an InfoDict Domain Descriptor is:

InfoDict:InfoDictName:[InfoDictID][:{ParentInfoDictID | ParentInfoDictName}]
[Tip]InfoHub Internals

Configuration processing stores InfoDict domain information in the following nodes:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber)=a??EndingSequenceNumber]:a??InfoDictName

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,0,a??ParentInfoDictID)a??=[EndingSequenceNumber]:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,a??"Children",a??ChildInfoDictID): this node is only maintained for the current configuration of this InfoHub.

Example:

InfoDict:GenericDict::SystemDict
 InfoDictItem:GenericDict:OpLog:1137
 InfoDictItem:GenericDict:AuthLog:1139

This example defines an InfoDict Domain called GenericDict and places two InfoDict Itemsa??OpLog and AuthLoga??under it. This example is a part of SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA

The InfoDictItem Descriptor can appear anywhere after the InfoHub Descriptor, except before an Env Descriptor, but most logically falls among or after any InfoDict [domain] Descriptors and before the Publisher Descriptors. InfoDictItems form the set of nodes the InfoHub can store. While you can create them explicitly, the configuration process can implicitly create InfoDictItems corresponding to some other InfoHub components (Publishers, xLines, Subscribers). The syntax of an InfoDictItem Descriptor is:

InfoDictItem:{InfoDictID | InfoDictName}:ItemName:[InfoDictItemID]:[Label]:[Type][;ItemDescription]

[Note]Note

When the same InfoHub has multiple adapters, the user-defined Types must be a superset of the Types required by all the adapters, and the transforms for each adapter must deal appropriately with all Types, including transforming those outside their set into those within their set.

[Tip]InfoHub Internals

Configuration processing stores InfoDict item information in the following nodes:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,ItemID)=[EndingSequenceNumber]:ItemName;Label:[Type]:[ItemDescription]

^InfoHubConf(InfoHubID,"InfoDicts","Dnames",InfoDictID,ItemName)=ItemID

^InfoHubConf(InfoHubID,"InfoDicts","Dnames",InfoDictName)=InfoDictID

^InfoHubConf(InfoHubID,BeginningSequenceNumber,"Paths",int1...)=ItemName;Label:[Type][:ItemDescription]

Example:

InfoDict:UpTime::UpTimeDict
+                                    Next

The InfoDictItem Descriptor can appear anywhere after the InfoHub Descriptor, except before an Env Descriptor, but most logically falls among or after any InfoDict [domain] Descriptors and before the Publisher Descriptors. InfoDictItems form the set of nodes the InfoHub can store. While you can create them explicitly, the configuration process can implicitly create InfoDictItems corresponding to some other InfoHub components (Publishers, xLines, Subscribers). The syntax of an InfoDictItem Descriptor is:

InfoDictItem:{InfoDictID | InfoDictName}:ItemName:[InfoDictItemID]:[Label]:[Type][;ItemDescription]

[Note]Note

When the same InfoHub has multiple adapters, the user-defined Types must be a superset of the Types required by all the adapters, and the transforms for each adapter must deal appropriately with all Types, including transforming those outside their set into those within their set.

[Tip]InfoHub Internals

Configuration processing stores InfoDict item information in the following nodes:

^InfoHubConf(InfoHubID,"InfoDicts",InfoDictID,BeginningSequenceNumber,ItemID)=[EndingSequenceNumber]:ItemName;Label:[Type]:[ItemDescription]

^InfoHubConf(InfoHubID,"InfoDicts","Dnames",InfoDictID,ItemName)=ItemID

^InfoHubConf(InfoHubID,"InfoDicts","Dnames",InfoDictName)=InfoDictID

^InfoHubConf(InfoHubID,BeginningSequenceNumber,"Paths",int1...)=ItemName;Label:[Type][:ItemDescription]

Example:

InfoDict:UpTime::UpTimeDict
 InfoDictItem:UpTime:Days:3030400::Integer:Days since last reboot
 InfoDictItem:UpTime:Load01:3030401::Float:One minute load average
 InfoDictItem:UpTime:Load05:3030405::Float:Five minute load average
diff --git a/applications/infohub/webhelp/content/ch04s06.html b/applications/infohub/webhelp/content/ch04s06.html
index 52a4247..c37c53a 100644
--- a/applications/infohub/webhelp/content/ch04s06.html
+++ b/applications/infohub/webhelp/content/ch04s06.html
@@ -34,7 +34,7 @@
                                         |
                                         Up
                                     |
-                                    Next

Information stored in an InfoHub is associated with information Publishers, each of which is specified with a Publisher descriptor. Publisher descriptors follow the InfoHub descriptor and any of its associated Environment Descriptors. While the meaning of "Publisher" is a function of a configuration and its conventions in your organization, it is appropriate for one Publisher to manage the information gathering and dissemination for one environment. This provides the PreExpr, PostExpr, and InfoExpr expressions of FileLine and PipeLine processes with an isolated environment where, if appropriate, they can communicate and cooperate with each other.

InfoHub JOBs a process for each Publisher. This process in turn JOBs processes for each FileLine or PipeLine descriptor associated with the Publisher. The Publisher process may optionally create a temporary directory before launching any processes. Within that temporary directory, it creates a global directory that maps to an unjournaled database in that temporary directory. It logs the name of the temporary directory to the InfoHub database.

The Publisher JOBs the FileLine or PipeLine processes with the following JOB Processparameters:

The syntax of a Publisher Descriptor is:

Publisher:{InfoDictID|InfoDictName}:[PublisherName]:[PublisherID]:[APIDir]:[TempPWD]:[TempDBAlloc]:[TempDBExtend]
[Tip]InfoHub Internals

The entryref used to start the FileLine and PipeLine processes includes a parameter for the Publisher process to pass its own global directory, which the FileLine and PipeLine processes use to record gathered information in the InfoHub and to communicate with the Publisher.

After launching FileLine and PipeLine processes, the Publisher schedules itself using HANG commands, periodically waking up to verify that its FileLine and PipeLine processes are active. During the HANG, it requires an interrupt to awaken it.

Configuration processing stores Publisher specification in the following nodes:

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber)a??=EndingSequenceNumber]:a??InfoDictID:a??[APIDir]:a??[TmpPWD]:a??[TmpDBAlloc]:a??[TmpDBExtend]

Example:

Publisher:SystemDict:System:::publishers/ihsyslog:1000:1000

This example configures a Publisher called System. This example is a part of the SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA

Information stored in an InfoHub is associated with information Publishers, each of which is specified with a Publisher descriptor. Publisher descriptors follow the InfoHub descriptor and any of its associated Environment Descriptors. While the meaning of "Publisher" is a function of a configuration and its conventions in your organization, it is appropriate for one Publisher to manage the information gathering and dissemination for one environment. This provides the PreExpr, PostExpr, and InfoExpr expressions of FileLine and PipeLine processes with an isolated environment where, if appropriate, they can communicate and cooperate with each other.

InfoHub JOBs a process for each Publisher. This process in turn JOBs processes for each FileLine or PipeLine descriptor associated with the Publisher. The Publisher process may optionally create a temporary directory before launching any processes. Within that temporary directory, it creates a global directory that maps to an unjournaled database in that temporary directory. It logs the name of the temporary directory to the InfoHub database.

The Publisher JOBs the FileLine or PipeLine processes with the following JOB Processparameters:

The syntax of a Publisher Descriptor is:

Publisher:{InfoDictID|InfoDictName}:[PublisherName]:[PublisherID]:[APIDir]:[TempPWD]:[TempDBAlloc]:[TempDBExtend]
[Tip]InfoHub Internals

The entryref used to start the FileLine and PipeLine processes includes a parameter for the Publisher process to pass its own global directory, which the FileLine and PipeLine processes use to record gathered information in the InfoHub and to communicate with the Publisher.

After launching FileLine and PipeLine processes, the Publisher schedules itself using HANG commands, periodically waking up to verify that its FileLine and PipeLine processes are active. During the HANG, it requires an interrupt to awaken it.

Configuration processing stores Publisher specification in the following nodes:

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber)a??=EndingSequenceNumber]:a??InfoDictID:a??[APIDir]:a??[TmpPWD]:a??[TmpDBAlloc]:a??[TmpDBExtend]

Example:

Publisher:SystemDict:System:::publishers/ihsyslog:1000:1000

This example configures a Publisher called System. This example is a part of the SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch04s07.html b/applications/infohub/webhelp/content/ch04s07.html index 0d08cd6..5554fc8 100644 --- a/applications/infohub/webhelp/content/ch04s07.html +++ b/applications/infohub/webhelp/content/ch04s07.html @@ -34,7 +34,7 @@ | Up | - Next

A FileLine descriptor defines aspects of monitoring a text file. For each FileLine entry in the configuration, the Publisher master process JOBs a process that reads the monitored file line by line, executing a GT.M expression (an extrinsic function call) for each line read in order to gather relevant information. The FileLine process OPENs the monitored file with the FOLLOW deviceparameter and then READs individual lines (the GT.M equivalent of tail -f).

The syntax of a FileLine descriptor is

FileLine:{InfoDictID | InfoDictName}:[FileLineName]:[FileLineID]:{PublisherID | PublisherName}:Filename:[CheckCycle]:[Timeout]:[PieceSeparator]:[PreExpr]:[InfoExpr]:[PostExpr]
[Tip]InfoHub Internals

On starting up, a FileLine process executes its PreExpr, gathering any information provided, and logging an error if the data does not match the expected format, as described earlier. In the event that PreExpr does not return an error, the FileLine process OPENs the file using the FOLLOW deviceparameter, and sits on an untimed READ of the file. Every line read gets processed by InfoExpr, and the returned data placed into the InfoHub database. Triggers on ^InfoHubInfo provide asynchronous notification to Subscribers; this eliminates polling to provide the most efficient processing (all other actions, including commands to shutdown, are sent via asynchronous interrupt-driven messages). In response to a shutdown command, the FileLine process executes its PostExpr, which may provide summary information, as appropriate, before shutting down.

GT.M V6.0-002 is the minimum compatible version because InfoHub uses the FOLLOW deviceparameter functionality which was first introduced in V6.0-002. For information on installing GT.M, refer to "Installing GT.M" chapter of the UNIX Administration and Operations Guide.

Configuration stores FileLine specifications in the following node:

^InfoHubConfInfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??FileLineID)=a?? EndingSequenceNumber]:a??FileName:a??InfoDictID:a??FileLineName:a??CheckCycle:a??Timeout:a??PieceSeparator]:a??[PreExpr]:a??[InfoExpr]:a??[PostExpr]

PreExpr, InfoExpr, and PostExpr always execute with $ZGBLDIR pointing to the global directory in the temporary directory. The FileLine process logs gathered information in the InfoHub database using an extended reference.

Example:

FileLine:GenericDict:OpLog::System:/var/log/messages:2:1:$char(30):PreExpr^LogFileGleaner:InfoExpr^LogFileGleaner:PostExpr^LogFileGleaner
FileLine:GenericDict:AuthLog::System:/var/log/auth.log:2:1:$char(30):PreExpr^LogFileGleaner:InfoExpr^LogFileGleaner:PostExpr^LogFileGleaner

This example configures two FileLine Gleaners, OpLog and AuthLog, as presented in the SimpleMonitor.conf configuration file in the ULFM Reference Implementation. The referenced PreExpr, InfoExpr, and PostExpr functions are implemented in "LogFileGleaner.m" (also available in the ULFM Reference Implementation), which provides a simple implementation of a gleaner that processes information from the system log.

PrevA UpA Next
A HomeA

A FileLine descriptor defines aspects of monitoring a text file. For each FileLine entry in the configuration, the Publisher master process JOBs a process that reads the monitored file line by line, executing a GT.M expression (an extrinsic function call) for each line read in order to gather relevant information. The FileLine process OPENs the monitored file with the FOLLOW deviceparameter and then READs individual lines (the GT.M equivalent of tail -f).

The syntax of a FileLine descriptor is

FileLine:{InfoDictID | InfoDictName}:[FileLineName]:[FileLineID]:{PublisherID | PublisherName}:Filename:[CheckCycle]:[Timeout]:[PieceSeparator]:[PreExpr]:[InfoExpr]:[PostExpr]
[Tip]InfoHub Internals

On starting up, a FileLine process executes its PreExpr, gathering any information provided, and logging an error if the data does not match the expected format, as described earlier. In the event that PreExpr does not return an error, the FileLine process OPENs the file using the FOLLOW deviceparameter, and sits on an untimed READ of the file. Every line read gets processed by InfoExpr, and the returned data placed into the InfoHub database. Triggers on ^InfoHubInfo provide asynchronous notification to Subscribers; this eliminates polling to provide the most efficient processing (all other actions, including commands to shutdown, are sent via asynchronous interrupt-driven messages). In response to a shutdown command, the FileLine process executes its PostExpr, which may provide summary information, as appropriate, before shutting down.

GT.M V6.0-002 is the minimum compatible version because InfoHub uses the FOLLOW deviceparameter functionality which was first introduced in V6.0-002. For information on installing GT.M, refer to "Installing GT.M" chapter of the UNIX Administration and Operations Guide.

Configuration stores FileLine specifications in the following node:

^InfoHubConfInfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??FileLineID)=a?? EndingSequenceNumber]:a??FileName:a??InfoDictID:a??FileLineName:a??CheckCycle:a??Timeout:a??PieceSeparator]:a??[PreExpr]:a??[InfoExpr]:a??[PostExpr]

PreExpr, InfoExpr, and PostExpr always execute with $ZGBLDIR pointing to the global directory in the temporary directory. The FileLine process logs gathered information in the InfoHub database using an extended reference.

Example:

FileLine:GenericDict:OpLog::System:/var/log/messages:2:1:$char(30):PreExpr^LogFileGleaner:InfoExpr^LogFileGleaner:PostExpr^LogFileGleaner
FileLine:GenericDict:AuthLog::System:/var/log/auth.log:2:1:$char(30):PreExpr^LogFileGleaner:InfoExpr^LogFileGleaner:PostExpr^LogFileGleaner

This example configures two FileLine Gleaners, OpLog and AuthLog, as presented in the SimpleMonitor.conf configuration file in the ULFM Reference Implementation. The referenced PreExpr, InfoExpr, and PostExpr functions are implemented in "LogFileGleaner.m" (also available in the ULFM Reference Implementation), which provides a simple implementation of a gleaner that processes information from the system log.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch04s08.html b/applications/infohub/webhelp/content/ch04s08.html index cfccc9f..5397f05 100644 --- a/applications/infohub/webhelp/content/ch04s08.html +++ b/applications/infohub/webhelp/content/ch04s08.html @@ -34,7 +34,7 @@ | Up | - Next

A PipeLine descriptor defines the aspects of monitoring output from a process. The monitored process can be a GT.M (any version) process or any other UNIX process. The Publisher master process JOBs a PipeLine process which reads the stdout and/or stderr of the monitored process line by line, executing a GT.M expression (an extrinsic function call) for each line read in order to gather and format the per-line information. As the name indicates, a PipeLine process uses a UNIX pipe to monitor a process.

The syntax of a PipeLine Descriptor is:

PipeLine:{InfoDictID | InfoDictName}:[PipeLineName]:[PipeLineID]:{PublisherID | PublisherName}:PipeCmd:[PipeCycle]:[Timeout]:[PieceSeparator]:[PreExpr]:[InfoExpr]:[PostExpr]:
[Tip]InfoHub Internals

On startup, each process for a PipeLine descriptor executes its PreExpr, gathering any information provided and logging an error if the data does not match the expected format, as described earlier. In the event PreExpr does not return an error, the PipeLine process OPENs the PipeCmd using a PIPE device and /bin/sh. The deviceparameters for the GT.M OPEN command used to start PipeCmd includes /bin/sh syntax set the environment appropriately. PipeCmd starts with environment variable changes as specified by ^InfoHubConf(InfoHubID,a??"Publishers",a??PublisherID,a??BeginningSequenceNumber,a??"EnvSetUp") for its Publisher as well as those specified in ^InfoHubConf(InfoHubID,a??"EnvSetUp",a??BeginningSequenceNumber) for descriptors applicable to the InfoHub itself (that is, applicable to all Publishers).

In the event the PipeCmd process terminates, the PipeLine process executes PostExpr, and terminates if PostExpr returns an error. Then, if PipeCycle is -1, the PipeLine process logs in the InfoHub database the fact that it is terminating and terminates. If PipeCycle is non-negative, the PipeLine process executes PreExpr, and if the return value is zero, starts a new invocation of PipeCmd.

Configuration processing stores PipeLine specifications in the following node:

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??PipeLineID)=a??[EndingSequenceNumber]:a??PipeCycle:a??InfoDictID:a??PipeLineName:a??PipeCmd:a??Timeout:a??[PieceSeparator]:a??[PreExpr]:a??[InfoExpr]:a??[PostExpr]

Example:

PipeLine:UpTimeDict:Uptime::System:/usr/bin/uptime:15:2:$char(30):PreExpr^UptimeGleaner:InfoExpr^UptimeGleaner:PostExpr^UptimeGleaner

This example configures a PipeLine gleaner for the uptime command. This example is a part of SimpleMonitor.conf in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA

A PipeLine descriptor defines the aspects of monitoring output from a process. The monitored process can be a GT.M (any version) process or any other UNIX process. The Publisher master process JOBs a PipeLine process which reads the stdout and/or stderr of the monitored process line by line, executing a GT.M expression (an extrinsic function call) for each line read in order to gather and format the per-line information. As the name indicates, a PipeLine process uses a UNIX pipe to monitor a process.

The syntax of a PipeLine Descriptor is:

PipeLine:{InfoDictID | InfoDictName}:[PipeLineName]:[PipeLineID]:{PublisherID | PublisherName}:PipeCmd:[PipeCycle]:[Timeout]:[PieceSeparator]:[PreExpr]:[InfoExpr]:[PostExpr]:
[Tip]InfoHub Internals

On startup, each process for a PipeLine descriptor executes its PreExpr, gathering any information provided and logging an error if the data does not match the expected format, as described earlier. In the event PreExpr does not return an error, the PipeLine process OPENs the PipeCmd using a PIPE device and /bin/sh. The deviceparameters for the GT.M OPEN command used to start PipeCmd includes /bin/sh syntax set the environment appropriately. PipeCmd starts with environment variable changes as specified by ^InfoHubConf(InfoHubID,a??"Publishers",a??PublisherID,a??BeginningSequenceNumber,a??"EnvSetUp") for its Publisher as well as those specified in ^InfoHubConf(InfoHubID,a??"EnvSetUp",a??BeginningSequenceNumber) for descriptors applicable to the InfoHub itself (that is, applicable to all Publishers).

In the event the PipeCmd process terminates, the PipeLine process executes PostExpr, and terminates if PostExpr returns an error. Then, if PipeCycle is -1, the PipeLine process logs in the InfoHub database the fact that it is terminating and terminates. If PipeCycle is non-negative, the PipeLine process executes PreExpr, and if the return value is zero, starts a new invocation of PipeCmd.

Configuration processing stores PipeLine specifications in the following node:

^InfoHubConf(InfoHubID,"Publishers",PublisherID,BeginningSequenceNumber,a??PipeLineID)=a??[EndingSequenceNumber]:a??PipeCycle:a??InfoDictID:a??PipeLineName:a??PipeCmd:a??Timeout:a??[PieceSeparator]:a??[PreExpr]:a??[InfoExpr]:a??[PostExpr]

Example:

PipeLine:UpTimeDict:Uptime::System:/usr/bin/uptime:15:2:$char(30):PreExpr^UptimeGleaner:InfoExpr^UptimeGleaner:PostExpr^UptimeGleaner

This example configures a PipeLine gleaner for the uptime command. This example is a part of SimpleMonitor.conf in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch04s09.html b/applications/infohub/webhelp/content/ch04s09.html index b96124c..22245a8 100644 --- a/applications/infohub/webhelp/content/ch04s09.html +++ b/applications/infohub/webhelp/content/ch04s09.html @@ -34,7 +34,7 @@ | Up | - Next

While the InfoHub database is available to any reader for asynchronous access without a need to be identified in the Configuration File, an InfoHub can also notify a reader when InfoHub data has a characteristic specified in a Subscription (see "Defining a Subscription"). For example, the Reference Implementation SNMP sub-agent uses this technique to generate SNMP traps without an asynchronous external request or polling. While most of the InfoHub works independently of any adapters, in order to perform asynchronous alerts or notifications, it requires some context for the Subscriber adapters. The syntax of the Subscriber Descriptor is:

Subscriber:{InfoDictID | InfoDictName}:[SubscriberName]:[SubscriberID]
[Tip]InfoHub Internals

When a Subscription detects an alert condition it queues the item (with a timestamp) under ^InfoHubInfo(InfoHubId,"Alerts") and INTRPTs all Subscribers attached to that Subscription. The Subscriber adapter process handles the queued alert item and KILLs its descendant node at its Subscriber ID; if there are no more Subscriber descendant nodes, it KILLs the queued item.

Configuration stores Subscriber specifications in the following node:

^InfoHubConf(InfoHubID,"Subscribers",SubscriberID,BeginningSequenceNumber)=a??[EndingSequenceNumber]:a??InfoDictID:SubscriberName

Example:

Subscriber:Reporters:SNMP:404
+                                    Next

While the InfoHub database is available to any reader for asynchronous access without a need to be identified in the Configuration File, an InfoHub can also notify a reader when InfoHub data has a characteristic specified in a Subscription (see "Defining a Subscription"). For example, the Reference Implementation SNMP sub-agent uses this technique to generate SNMP traps without an asynchronous external request or polling. While most of the InfoHub works independently of any adapters, in order to perform asynchronous alerts or notifications, it requires some context for the Subscriber adapters. The syntax of the Subscriber Descriptor is:

Subscriber:{InfoDictID | InfoDictName}:[SubscriberName]:[SubscriberID]
[Tip]InfoHub Internals

When a Subscription detects an alert condition it queues the item (with a timestamp) under ^InfoHubInfo(InfoHubId,"Alerts") and INTRPTs all Subscribers attached to that Subscription. The Subscriber adapter process handles the queued alert item and KILLs its descendant node at its Subscriber ID; if there are no more Subscriber descendant nodes, it KILLs the queued item.

Configuration stores Subscriber specifications in the following node:

^InfoHubConf(InfoHubID,"Subscribers",SubscriberID,BeginningSequenceNumber)=a??[EndingSequenceNumber]:a??InfoDictID:SubscriberName

Example:

Subscriber:Reporters:SNMP:404
 Subscriber:Reporters:NAGIOS:503

This example configures two subscribersa??SNMP and NAGIOS. This example is a part of SimpleMonitor.conf in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA

InfoHub implements alerts and notifications with GT.M triggers on ^InfoHubInfo nodes. With one exception, a Subscription Descriptor essentially defines a trigger. A Subscription Descriptor specifying a condition of "Noinfo" differs slightly, in that it starts a Noinfo process which periodically checks for data in ^InfoHubInfo and if it finds none, places a "key:value" pair in the alert queue and sends an INTRPT to its Subscriber process(es). The syntax of the Subscriber Descriptor is:

Subscription:{InfoDictID | InfoDictName}:[SubscriptionName]: [SubscriptionID]:{InfoDictID | InfoDictName}:{InfoDictItemID | InfoDictItemName}:Condition:[Value]:[Period]:[entryref]:[SubscriberID[,...]]:[PublisherID[,...]]
[Tip]InfoHub Internals

InfoHub implements other alerts with GT.M triggers on InfoHub nodes. A Subscription Descriptor other than "Noinfo" defines a trigger.

The technique of using GT.M triggers to implement Subscriptions does not work for NoInfo Subscriptions because triggers are initiated by a database update, whereas NoInfo is initiated by the absence of an update. To manage polling impact, each NoInfo subscription is implemented with a process that executes a Hang for the Period at the end of which it might need to queue an alert and INTRPT one or more Subscribers. When the Hang expires, the process checks whether or not the information it is monitoring has changed. If it has, the process notes the time at which it changed, and schedules itself for the future with another Hang. If it has not changed, the process makes an appropriate entry in ^InfoHubInfo, issues the alert / notification, and schedules itself for the future with a Hang for the Period. Because the META type aggregation mechanism uses a trigger on a node that manages Subscriber notifications for its Subscription and suppresses storing of data at the trigger node, a NoInfo process has no means to track activity at a META node.

Configuration processing stores Subscription specifications in the following nodes:

InfoHubConf(InfoHubID,"Subscriptions",SubscriptionID,BeginningSequenceNumber)=a?? [EndingSequenceNumber]:a??SubscriptionInfodictID:a??ItemInfoDictID:a??InfoDictID:a??condition:a??value:a??[period]:a??[entryref]:a??[SubscriberID[,...]]:a??[PublisherID[,...]]

^InfoHubConf(InfoHubID,"NoInfo",SubscriptionID,BeginningSequenceNumber)=a??

Example:

Subscription:SysSubscriptions:PatchMe:1000:UpTime:Days:<:30:::404:
+                                    Next

InfoHub implements alerts and notifications with GT.M triggers on ^InfoHubInfo nodes. With one exception, a Subscription Descriptor essentially defines a trigger. A Subscription Descriptor specifying a condition of "Noinfo" differs slightly, in that it starts a Noinfo process which periodically checks for data in ^InfoHubInfo and if it finds none, places a "key:value" pair in the alert queue and sends an INTRPT to its Subscriber process(es). The syntax of the Subscriber Descriptor is:

Subscription:{InfoDictID | InfoDictName}:[SubscriptionName]: [SubscriptionID]:{InfoDictID | InfoDictName}:{InfoDictItemID | InfoDictItemName}:Condition:[Value]:[Period]:[entryref]:[SubscriberID[,...]]:[PublisherID[,...]]
[Tip]InfoHub Internals

InfoHub implements other alerts with GT.M triggers on InfoHub nodes. A Subscription Descriptor other than "Noinfo" defines a trigger.

The technique of using GT.M triggers to implement Subscriptions does not work for NoInfo Subscriptions because triggers are initiated by a database update, whereas NoInfo is initiated by the absence of an update. To manage polling impact, each NoInfo subscription is implemented with a process that executes a Hang for the Period at the end of which it might need to queue an alert and INTRPT one or more Subscribers. When the Hang expires, the process checks whether or not the information it is monitoring has changed. If it has, the process notes the time at which it changed, and schedules itself for the future with another Hang. If it has not changed, the process makes an appropriate entry in ^InfoHubInfo, issues the alert / notification, and schedules itself for the future with a Hang for the Period. Because the META type aggregation mechanism uses a trigger on a node that manages Subscriber notifications for its Subscription and suppresses storing of data at the trigger node, a NoInfo process has no means to track activity at a META node.

Configuration processing stores Subscription specifications in the following nodes:

InfoHubConf(InfoHubID,"Subscriptions",SubscriptionID,BeginningSequenceNumber)=a?? [EndingSequenceNumber]:a??SubscriptionInfodictID:a??ItemInfoDictID:a??InfoDictID:a??condition:a??value:a??[period]:a??[entryref]:a??[SubscriberID[,...]]:a??[PublisherID[,...]]

^InfoHubConf(InfoHubID,"NoInfo",SubscriptionID,BeginningSequenceNumber)=a??

Example:

Subscription:SysSubscriptions:PatchMe:1000:UpTime:Days:<:30:::404:
 Subscription:SysSubscriptions:AuthFail:2000:GenericAny:Anything:[:""""Fail"""":::503:
 Subscription:SysSubscriptions:GTMError:3000:GenericAny:Anything:[:""""%GTM-E""""::::

This example configures 3 subscriptionsa??PatchMe, AuthFail, and GTMError. PatchMe is for Subscriber ID 404 and AuthFail is for Subscriber ID 503. GTMError is for all Subscribers. This example is a part of SimpleMonitor.conf configuration file in the ULFM Reference Implementation.

PrevA UpA Next
A HomeA
loading table of contents...

[Tip]InfoHub Internals

When an xLine receives a string consisting of key-value pairs, it processes each pair individually. First, InfoHub verifies the existence of the following node to ascertain whether there is a Path in the configuration which matches the <key>:

^InfoHubConf(<InfoHubID>,<InfoHubSeqNo>,"Paths",<PublisherID>,<xLineID>,<key>)

If the node exists and is of non-META type, InfoHub performs the following three updates:

  1. ^InfoHubInfo(<InfoHubID>,<PublisherID>,<PipeLineID>,<key>,<seqno>)=":<type>:<value>"

  2. ^InfoHubInfo(<InfoHubID>,"TimeToSeqNo",<PublisherID>,<PipeLineID>,<key>,<time>,<seqno>)=""

  3. ^InfoHubInfo(<InfoHubID>,"SeqNoToTime",<PublisherID>,<PipeLineID>,<key>,<seqno>)=<time>

where <value> is the one corresponding to the current key; <type> is as specified in the ^InfoHubConf(...,"Paths",...) node; and <seqno> is the current sequence number for this key. "TimeToSeqNo" and "SeqNoToTime" are ancillary nodes that InfoHub uses to perform book-keeping functions. InfoHub skips the first of these updates if the value for a particular key did not change from the last time. Otherwise, InfoHub "closes" the previous update by providing the ending sequence number in the value:

^InfoHubInfo(<InfoHubID>,<PublisherID>,<xLineID>,<key>,<seqno>)="<ending seqno>:<type>:<value>"

Suppose the prior value for key 9999 was .77 and the current value is .64. The following node represents the InfoHub database update at the time when key 9999 was .77:

^InfoHubInfo(11,112,1137,9999,87)=":String:.77"

The following nodes represent InfoHub database updates when the value corresponding to key 9999 changes to .64.

  • ^InfoHubInfo(11,112,1137,9999,87)="88:String:.77"

  • ^InfoHubInfo(11,112,1137,9999,88)=":String:.64"

Here 88 is the ending sequence number of the prior value. The change for key 9999's corresponding value to .64 also adds the following nodes:

  • ^InfoHubInfo(11,"SeqNoToTime",112,1137,9999,88)="1385382167772674"

  • ^InfoHubInfo(11,"TimeToSeqNo",112,1137,9999,1385382167772674,88)=""

In case of META nodes, it performs the following update in addition to the updates to the node causing the META action:

  • ^InfoHubInfo(<InfoHubID>,"Alerts",<PublisherID>",<xLineID>,<key>)="<time>:<SubscriptionID>:info:ref:<last non-meta path for this event >"

PrevA UpA Next
A HomeA
loading table of contents...

[Tip]InfoHub Internals

When an xLine receives a string consisting of key-value pairs, it processes each pair individually. First, InfoHub verifies the existence of the following node to ascertain whether there is a Path in the configuration which matches the <key>:

^InfoHubConf(<InfoHubID>,<InfoHubSeqNo>,"Paths",<PublisherID>,<xLineID>,<key>)

If the node exists and is of non-META type, InfoHub performs the following three updates:

  1. ^InfoHubInfo(<InfoHubID>,<PublisherID>,<PipeLineID>,<key>,<seqno>)=":<type>:<value>"

  2. ^InfoHubInfo(<InfoHubID>,"TimeToSeqNo",<PublisherID>,<PipeLineID>,<key>,<time>,<seqno>)=""

  3. ^InfoHubInfo(<InfoHubID>,"SeqNoToTime",<PublisherID>,<PipeLineID>,<key>,<seqno>)=<time>

where <value> is the one corresponding to the current key; <type> is as specified in the ^InfoHubConf(...,"Paths",...) node; and <seqno> is the current sequence number for this key. "TimeToSeqNo" and "SeqNoToTime" are ancillary nodes that InfoHub uses to perform book-keeping functions. InfoHub skips the first of these updates if the value for a particular key did not change from the last time. Otherwise, InfoHub "closes" the previous update by providing the ending sequence number in the value:

^InfoHubInfo(<InfoHubID>,<PublisherID>,<xLineID>,<key>,<seqno>)="<ending seqno>:<type>:<value>"

Suppose the prior value for key 9999 was .77 and the current value is .64. The following node represents the InfoHub database update at the time when key 9999 was .77:

^InfoHubInfo(11,112,1137,9999,87)=":String:.77"

The following nodes represent InfoHub database updates when the value corresponding to key 9999 changes to .64.

  • ^InfoHubInfo(11,112,1137,9999,87)="88:String:.77"

  • ^InfoHubInfo(11,112,1137,9999,88)=":String:.64"

Here 88 is the ending sequence number of the prior value. The change for key 9999's corresponding value to .64 also adds the following nodes:

  • ^InfoHubInfo(11,"SeqNoToTime",112,1137,9999,88)="1385382167772674"

  • ^InfoHubInfo(11,"TimeToSeqNo",112,1137,9999,1385382167772674,88)=""

In case of META nodes, it performs the following update in addition to the updates to the node causing the META action:

  • ^InfoHubInfo(<InfoHubID>,"Alerts",<PublisherID>",<xLineID>,<key>)="<time>:<SubscriptionID>:info:ref:<last non-meta path for this event >"

PrevA UpA Next
A HomeA
loading table of contents...
diff --git a/applications/infohub/webhelp/content/ch05s02.html b/applications/infohub/webhelp/content/ch05s02.html index 155f012..900194a 100644 --- a/applications/infohub/webhelp/content/ch05s02.html +++ b/applications/infohub/webhelp/content/ch05s02.html @@ -35,9 +35,9 @@ Up | Next

The FIS GT.M SNMP Plugin is a ready-to-use subagent that makes information from InfoHub available for monitoring via SNMP. It uses the Internet standard (RFC-2741) AgentX protocol to communicate with an SNMP Master Agent. Because FIS tests the SNMP Plugin with Net-SNMP ( http://www.net-snmp.org) as the SNMP Master Agent, Net-SNMP is Supported and other SNMP Master Agents are Supportable but not Supported.

The SNMP Plugin is a Reporting Adaptor that has both Query and Subscriber relationships with InfoHub. The following diagram illustrates how the SNMP Plugin interacts with InfoHub to handle requests for data retrieval and notifications from an SNMP environment.

- SNMP Plugin in SNMP environment + SNMP Plugin in SNMP environment

A data retrieval request initiated from CLI applications such as snmpget/snmpgetnext goes to the Master SNMP Agent using the SNMP protocol. The Master SNMP Agent uses the AgentX protocol to communicate the request to the SNMP Plugin which uses its Query relationship with InfoHub to retrieve the requested data and sends it to back to the Master SNMP Agent. CLI applications such as snmptrapd set up a listener for receiving notifications. When a configured condition occurs on InfoHub, the SNMP Plugin uses its Subscriber relationship to obtain notification details and sends them to the SNMP Master Agent which then sends it to the listener waiting for notifications.

In an SNMP environment, data values are organized in a tree structure called an MIB (Management Information Base). The MIB hierarchy starts with a nameless root and extends to specific areas of information. Typically, an organization has several MIB modules connected hierarchically with each other. Each object is addressed using a fully qualified OID starting from the nameless root. An OID can be represented in numeric or mnemonic form. A fully qualified OID in numeric form looks like:

.1.3.6.1.4.1.16830.6.2.1.2.1.1482247793.1.314.0

The same OID in mnemonic form might looks like:

.iso.org.dod.internet.private.enterprises.fis.profile.gtm.infohub.profile1curr.uatenv1curr.syslogcurr.SyslogAllcurr.0

The following diagram illustrates the fully qualified OID .1.3.6.1.4.1.16830.6.2.1.2.1.1482247793.1.314.0 in an MIB that contains an InfoHub MIB module sub-tree. The numeric forms are enclosed in brackets ().

- InfoDict GT.M monitoring example + InfoDict GT.M monitoring example

The non-white boxes represent the OID sub-subtree in the InfoHub MIB module. In the illustration, the InfoHub MIB module hierarchy starts from 16830.6.2 where:

  • fis (16830) identifies the enterprise FIS.

  • profile (6) identifies the FIS Profile product. Within FIS, all OIDs below .16830.6. are reserved for use by the FIS Profile family of products.

  • gtm (2) identifies GT.M. OIDs below 16830.6.2 are for sub-trees of InfoHubs. The depth of each InfoHub OID sub-tree can vary depending on its InfoHub Configuration File.

  • infohub (1) represents the level for InfoHubs.

  • profile1curr (2) represents the current View of an instance of one InfoHub.

  • uatenv1curr(1482247793) represents the current View of the Publisher.

  • syslogcurr (1) represents the current View of the FileLine Gleaner for the system log.

  • SyslogAllcurr (15037) is a grouping that represents all messages filed in the system log.

InfoHub maintains the current and historic data values of monitored elements in the form of Views. InfoHub provides four Views a?? curr, hist, time, and snum. Views are different ways of looking at the current and historic data values of an object. A View is like a filter applied on an object to narrow down to only those data values that you want to see from an InfoHub. Every object under an InfoHub has four stems each representing a View. All objects under a stem have the same View Name as the suffix. The last (leaf) node of each stem is the monitored object for which you need to specify a parameter called an Object Index.

The objective of stemming of the same object into four Views is to comply with the namespace restriction that all individual pieces of an OID in an MIB to be unique. The non-white boxes in the OID illustrate a fully qualified mnemonic OID of the most recent (curr) object stored on the system log and the curved connectors denote stemming into Views. Notice how each object under .profilecurr has the curr suffix and the leaf node requires specifying an Object Index[2].

To obtain the current or historic data of any monitored element, you need to perform a GET request (refer to "Performing a GET Request") for either the fully qualified OID as illustrated in the OID diagram or just the leaf node (for example, .infohubprofile1uatenv1SyslogAllcurr.0).

The four Views are as follows:

View Name (mnemonic suffix)

 diff --git a/applications/infohub/webhelp/content/ch05s03.html b/applications/infohub/webhelp/content/ch05s03.html index b49e118..4c3ddc4 100644 --- a/applications/infohub/webhelp/content/ch05s03.html +++ b/applications/infohub/webhelp/content/ch05s03.html @@ -58,7 +58,7 @@

SNMP (Simple Network Management Protocol) agents

-
[Note]Note

Although the InfoHub SNMP plug-in uses NET-SNMP, NET-SNMP is not FIS software and FIS does not support NET-SNMP. The sample instructions for installing and configuring NET-SNMP are merely provided as a convenience to you.

On Ubuntu, the command to download and install these packages is:

$ sudo aptitude install snmpd snmp snmp-mibs-downloader
[Note]AIX Notes

For testing the SNMP Plugin on AIX, the FIS GT.M Team built net-snmp 5.7.2 using the following commands:

./configure --disable-shared --without-kmem-usage
+
[Note]Note

Although the InfoHub SNMP plug-in uses NET-SNMP, NET-SNMP is not FIS software and FIS does not support NET-SNMP. The sample instructions for installing and configuring NET-SNMP are merely provided as a convenience to you.

On Ubuntu, the command to download and install these packages is:

$ sudo aptitude install snmpd snmp snmp-mibs-downloader
[Note]AIX Notes

For testing the SNMP Plugin on AIX, the FIS GT.M Team built net-snmp 5.7.2 using the following commands:

./configure --disable-shared --without-kmem-usage
 make
 make test 
 sudo make install

To start net-snmp, execute the following command:

sudo /usr/local/sbin/snmpd

To stop net-snmp, execute the following commands:

sudo /usr/local/sbin/snmpd
@@ -88,7 +88,7 @@ informsink 127.0.0.1 <communitystring>
 ## Have snmpd run as a master agent
 master agentx
 # Tell snmpd where to listen for Agentx connections
-agentXSocket tcp:127.0.0.1:705

Replace <communitystring> with an appropriate password. <communitystring> is used to authenticate SNMPv1/v2c transactions.

[Note]AIX Notes

To allow NET-SNMP and AIX's native snmp to coexist, assign a new port for the NET-SNMP agent by modifying the agentAddress line in snmp.conf:

agentAddress  udp:127.0.0.1:9716

If NET-SNMP was installed from binaries, please note down what port number was assigned as this will be needed by snmpget, snmpgetnext, etc. For example: 

agentAddress  udp:127.0.0.1:1610

  • Using your favorite editor, open /etc/snmp/snmptrapd.conf as user root (via sudo), and if /etc/snmp/snmptrapd.conf does not exist, create it with R/W only permission for user root (root-only access is needed to protect the community string). Add the following line to /etc/snmp/snmptrapd.conf:

    authCommunity log <communitystring>

    Replace <communitystring> with the same password that you used in step 5.

  • Restart your network management services to apply changes in snmpd.conf and snmptrapd.conf. On Ubuntu, the command is:

    $ sudo service snmpd restart

  • Set up the environment for your InfoHub and execute the following command to generate the MIB module from InfoHub. 

    $gtm_dist/mumps -r generatemib >INFOHUB-1-MIB

  • Place INFOHUB-1-MIB in one of the directories in the MIB search path, for example, /usr/local/share/snmp/mibs. This allows both you and snmptrapd (discussed later) to access it.

  • Congratulations! The SNMP Plugin is now installed on your system. Perform step 8 and 9 every time there is a change to the InfoHub configuration that impacts the structure of InfoHub or the objects available. You do not need to perform these steps if your updates neither impacts the InfoHub structure nor alters the number of objects available, for example updating a subscription condition.

    • PrevA UpA Next
    A HomeA
    loading table of contents...
    PrevA UpA Next
    A HomeA
    loading table of contents...
    diff --git a/applications/infohub/webhelp/content/ch05s08.html b/applications/infohub/webhelp/content/ch05s08.html index 46f53f1..befc1ff 100644 --- a/applications/infohub/webhelp/content/ch05s08.html +++ b/applications/infohub/webhelp/content/ch05s08.html @@ -66,7 +66,7 @@ With time View:

    The time View is only available with snmpgetnext. Because time is specified in seconds since the last UNIX epoch and InfoHub time granularity is much less than one second, snmpget is not able to determine the exact time. For more information see "Performing a GETNEXT request".

    With snum View: - 

    $ snmpget -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB localhost INFOHUB-1-MIB::infohubtestMyBoxSyslogGTMFatalsnum.1011912

    This example retrieves the data value of a GT.M Fatal error stored on InfoHub with sequence number 1011912. In most cases, you would use the snum View in conjunction with the time View which returns the sequence number of the monitored object's mnemonic OID.

    [Note]AIX Notes

    On AIX, you need to explicitly specify the port number for the NET-SNMP Agent since another port was assigned during installation (see the agentAddress line in snmpd.conf). A sample snmpget command might look like:

    snmpget -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB 127.0.0.1:9716 INFOHUB-1-MIB::infohubtestMyBoxSyslogAllcurr.0

    or:

    snmpget -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB 127.0.0.1:1610 INFOHUB-1-MIB::infohubtestMyBoxSyslogAllcurr.0
    PrevA UpA Next
    A HomeA
    loading table of contents...
    diff --git a/applications/infohub/webhelp/content/ch05s09.html b/applications/infohub/webhelp/content/ch05s09.html index feb9e27..31a3254 100644 --- a/applications/infohub/webhelp/content/ch05s09.html +++ b/applications/infohub/webhelp/content/ch05s09.html @@ -68,7 +68,7 @@ INFOHUB-1-MIB::infohubtestInfoHubOID = OID: INFOHUB-1-MIB::infohubtestMyBoxSyslogGTMFatalsnum.19

    This example retrieves the mnemonic OID and the sequence number of the first fatal GT.M error that was stored on Infohub after 10/09/2013 14:26:00. This View is useful in situations where you need to investigate incidents occurring around a specified time.

    With snum View: 

    $ snmpgetnext -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB localhost INFOHUB-1-MIB::infohubtestMyBoxSyslogGTMFatalsnum.18
-INFOHUB-1-MIB::infohubtestMyBoxSyslogGTMFatalsnum.19 = STRING: "Oct  9 19:06:07 gtmnode20 GTM-SRCSRVR-INSTANCE1[14796]: %GTM-F-FORCEDHALT, Image HALTed by MUPIP STOP -- generated from 0x0000000000000000."

    This example uses the sequence number (snum.18) returned with the time View example to retrieve the data value of the next GT.M Fatal error stored on InfoHub immediately after sequence number 18. In most cases, you would use the snum View in conjunction with the time View which returns the sequence number of the monitored object's mnemonic OID.

    You can also use the snmpbulkget command to display the next 10 data values of objects stored in InfoHub after sequence number 18. 

    $ snmpbulkget -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB localhost INFOHUB-1-MIB::infohubtestMyBoxSyslogGTMFatalsnum.18

    You can also specify -Cr20 to retrieve the next 20 data values of objects stored in InfoHub after sequence number 18.

    [Note]AIX Notes

    On AIX, you need to explicitly specify the port number for the NET-SNMP Agent since another port was assigned during installation (see the agentAddress line in snmpd.conf). A sample snmpgetnext command might look like:

    snmpgetnext -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB 127.0.0.1:9716 INFOHUB-1-MIB::infohubtestMyBoxSyslogAllcurr.0

    or:

    snmpgetnext -v2c -c <communitystring> -Oa -m INFOHUB-1-MIB 127.0.0.1:1610 INFOHUB-1-MIB::infohubtestMyBoxSyslogAllcurr.0
    PrevA UpA Next
    A HomeA
    loading table of contents...
    diff --git a/applications/infohub/webhelp/content/ch05s11.html b/applications/infohub/webhelp/content/ch05s11.html index 72891af..422c219 100644 --- a/applications/infohub/webhelp/content/ch05s11.html +++ b/applications/infohub/webhelp/content/ch05s11.html @@ -59,7 +59,7 @@ SNMPv2-SMI::snmpModules.1.1.4.1.0 = OID: INFOHUB-1-MIB::infohubtestMyBoxSyslogDBFILEXTcurr.0 2013-10-23 03:34:10 localhost.localdomain [UDP: [127.0.0.1]:54501->[127.0.0.1]]: SNMPv2-SMI::mib-2.1.3.0 = Timeticks: (118883997) 13 days, 18:13:59.97 -SNMPv2-SMI::snmpModules.1.1.4.1.0 = OID: INFOHUB-1-MIB::infohubtestMyBoxSyslogDBFILEXTcurr.0

    This example sets up a listener for notifications coming from InfoHub. -Lo specifies that the messages are logged on standard output. The DBFILEXT notification that arrives on snmptrapd is from a Noinfo subscription called DBFILEXT which InfoHub raised due to lack of activity for the DBFILEXT message.

    [Note]AIX Notes

    On AIX, use the NET-SNMP executable to set up a listener for notifications coming from InfoHub. A sample snmptrapd command might look like:

    sudo /usr/local/sbin/snmptrapd -m INFOHUB-1-MIB -Oa -Lo -f -t
    PrevA UpA Next
    A HomeA
    loading table of contents...
    diff --git a/applications/infohub/webhelp/content/ch06s03.html b/applications/infohub/webhelp/content/ch06s03.html index d630ca6..8b28627 100644 --- a/applications/infohub/webhelp/content/ch06s03.html +++ b/applications/infohub/webhelp/content/ch06s03.html @@ -34,10 +34,10 @@ | Up | - Next

    The Uptime and Log File Monitoring (ULFM) Reference Implementation monitors:

    The following table contains information about all files that are a part of the ULFM Reference Implementation. You can view these files from the configs subdirectory of your InfoHub distribution where they reside or download them from the links in the table. You can also click Download ULFM Implementation to download all files of the ULFM Reference Implementation together or open directly from http://tinco.pair.com/bhaskar/gtm/applications/infohub/ULFM_RI.zip.

    Component

    Name

    Description

    Download

    InfoHub Main Configuration File

    SimpleMonitor.conf

    The InfoHub configuration file used to configure the ULFM Reference Implementation. For uptime, it defines InfoDict Items Load01, Load05, and Load15 to store load averages, and Days to store up days. There are two subscriptionsa??PatchMe to send a notification when Days is greater than 30 and DontBeLazy to send a notification when Load15 is less than 1. For log files, it defines an InfoDict Item called Anything to hold the value of line read from each log file. For this item, it defines two subscriptionsa??AuthFail to send an alert when Anything contains ([) "Fail" and GTMError to send an alert when Anythingcontains ([) "%GTM-E".

    Download SimpleMonitor.conf

    FileLine Gleaner

    LogFileGleaner.m

    A simple FileLine gleaner program that reads every line of the /var/log/messages and /var/log/auth.log and returns value in the form of 9999:line_read_value. Note that 9999 is the InfoDict Id for msg. PreExpr gets invoked before processing the log file and defines configuration options and PostExpr gets invoked after completion of log file processing and removes configuration options defined in PreExpr.

    Download LogFileGleaner.m

    PipeLine Gleaner

    UptimeGleaner.m

    A simple PipeLine gleaner program for the uptime command. It returns values in the multiples of <key>:<value> in the form of 3030400:Days :3030401:Load:3030405:Load5:3030415:Load15 for every line read from the uptime output. PreExpr gets invoked prior before processing uptime and defines configuration options. PostExpr gets invoked after completion of uptimeprocessing and removes configuration options defined in PreExpr. InfoHub invokes the UptimeGleaner every 15 seconds.

    Download UptimeGleaner.m

    + Next

    The Uptime and Log File Monitoring (ULFM) Reference Implementation monitors:

    The following table contains information about all files that are a part of the ULFM Reference Implementation. You can view these files from the configs subdirectory of your InfoHub distribution where they reside or download them from the links in the table. You can also click Download ULFM Implementation to download all files of the ULFM Reference Implementation together or open directly from http://tinco.pair.com/bhaskar/gtm/applications/infohub/ULFM_RI.zip.

    Component

    Name

    Description

    Download

    InfoHub Main Configuration File

    SimpleMonitor.conf

    The InfoHub configuration file used to configure the ULFM Reference Implementation. For uptime, it defines InfoDict Items Load01, Load05, and Load15 to store load averages, and Days to store up days. There are two subscriptionsa??PatchMe to send a notification when Days is greater than 30 and DontBeLazy to send a notification when Load15 is less than 1. For log files, it defines an InfoDict Item called Anything to hold the value of line read from each log file. For this item, it defines two subscriptionsa??AuthFail to send an alert when Anything contains ([) "Fail" and GTMError to send an alert when Anythingcontains ([) "%GTM-E".

    Download SimpleMonitor.conf

    FileLine Gleaner

    LogFileGleaner.m

    A simple FileLine gleaner program that reads every line of the /var/log/messages and /var/log/auth.log and returns value in the form of 9999:line_read_value. Note that 9999 is the InfoDict Id for msg. PreExpr gets invoked before processing the log file and defines configuration options and PostExpr gets invoked after completion of log file processing and removes configuration options defined in PreExpr.

    Download LogFileGleaner.m

    PipeLine Gleaner

    UptimeGleaner.m

    A simple PipeLine gleaner program for the uptime command. It returns values in the multiples of <key>:<value> in the form of 3030400:Days :3030401:Load:3030405:Load5:3030415:Load15 for every line read from the uptime output. PreExpr gets invoked prior before processing uptime and defines configuration options. PostExpr gets invoked after completion of uptimeprocessing and removes configuration options defined in PreExpr. InfoHub invokes the UptimeGleaner every 15 seconds.

    Download UptimeGleaner.m

    To install the ULFM Reference Implementation, perform the following steps:

    1. Install InfoHub and create an InfoHub database. For more information, refer to Installing InfoHub.

    2. From the samples directory copy SimpleMonitor.conf to the configs directory.

    3. Execute the following command to load the SimpleMonitor.conf configuration file and start InfoHub.

      $ $gtm_dist/mumps -run InfoHub --action=configure --file=$ihsrcdir/configs/SimpleMonitor.conf
      $ $gtm_dist/mumps -run InfoHub --action=start

      For more information, refer to Loading a Configuration File and Starting an InfoHub.

    4. Install the FIS GT.M SNMP Plugin. For installation instructions and prerequisites, refer to Installing the SNMP Plugin.

    5. Execute the following command to start the SNMP Plugin using Subscriber Id 404. Note that the SNMP Subscriber Descriptor (entry starting with Subscriber:) in SimpleMonitor.conf specifies 404 as the Subscriber Id for uptime notifications and 503 as Subscriber Id for log file notifications.

      $ $gtm_dist/mumps -run IHsnmp --action=start --plugin=404

      For more information, refer to Starting the SNMP Plugin.

    6. Execute the following commands to check the status of InfoHub and the SNMP Plugin:

      $ $gtm_dist/mumps -run InfoHub --action=status 
      $ $gtm_dist/mumps -run IHsnmp --action=status --plugin=404

      For more information, refer to Monitoring an InfoHub and Monitoring the SNMP Plugin.

    7. Congratulations! Your ULFM Reference Implementation is now installed .

    The following illustration shows how the ULFM Reference Implementation sets up an InfoHub framework for monitoring.

    - ULFM Reference Implementation setup + ULFM Reference Implementation setup

    PrevA UpA Next
    A HomeA
    loading table of contents...

    Although GTMJI may as well work on other combinations of platforms and Java implementations, the above are the platforms on which GTMJI is tested. Versions of each platform are those on which your GT.M is supported per the release notes for that release.

    [Note]Download Examples

    gtmji-demo.zip contains examples of Java programs, call-in/call-out tables, and GT.M APIs described in this technical bulletin. To download gtmji-demo.zip, click Download gtmji-demo.zip or open directly from http://tinco.pair.com/bhaskar/gtm/doc/articles/gtmji-demo.zip. For instruction on running call-in examples, see the code comments of CI.java or JPiece.java. For instructions on running the call-out example, see the code comments of CO.java.

    Installation

    GTMJI comes with a Makefile that you can use with GNU make to build, test, install, and uninstall the package. On some platforms, GNU make may be accessed with the command gmake, not make. You can build and test GTMJI as a normal (non-root) user, and then as root install it as a GT.M plug-in. The targets in Makefile that are intended for external use are

    • all: creates libgtmj2m.so and libgtmm2j.so (shared libraries of C code that acts as a gateway for Java call-ins and call-outs, respectively) and gtmji.jar (a Java archive containing GTMJI type wrapper and thread management classes).

    • clean: deletes all files created as a result of running the test and/or all target.

    • install: executed as root, installs GTMJI as a plug-in under the GT.M installation directory.

    • install-test: executed as root, ensures the operation of GTMJI after building and installation. Messages "GTMJI-INSTALL-SUCCESS: Call-ins test succeeded." and "GTMJI-INSTALL-SUCCESS: Call-outs test succeeded." confirm successful installation. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.

    • test: ensures the operation of GTMJI after building and before installation. As with the install-test target, "GTMJI-INSTALL-SUCCESS: Call-ins test succeeded." and "GTMJI-INSTALL-SUCCESS: Call-outs test succeeded." messages should appear. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.

    • uninstall: executed as root, removes the installed plug-in from under the GT.M installation directory.

    The following targets also exist but are intended for use within the Makefile rather than for external invocation: libgtmj2m.so, libgtmm2j.so, gtmji.jar, $(PLUGINDIR)/libgtmj2m.so, $(PLUGINDIR)/libgtmm2j.so, $(PLUGINDIR)/gtmji.jar, $(UTFPLUGINDIR)/libgtmj2m.so, $(UTFPLUGINDIR)/libgtmm2j.so, and $(UTFPLUGINDIR)/gtmji.jar.

    To run the Makefile, set the following environment variables:

    • gtm_dist: Installation directory of GT.M that contains libgtmshr.so and such include files as gtm_common_defs.h and gtmxc_types.h. If you plan to install GTMJI for multiple GT.M versions, please clean the build each time, since both gtmxc_types.h and gtm_common_defs.h are included from $gtm_dist to build the shared library.

    • JAVA_HOME: Top directory of your Java installation, such as /usr/lib/jvm/jdk1.6.0_25.

    • JAVA_SO_HOME: Directory that contains libjava.so; typically,

      • AIX: $JAVA_HOME/jre/lib/ppc64

      • Linux: $JAVA_HOME/jre/lib/amd64, $JAVA_HOME/jre/lib/i386, or $JAVA_HOME/jre/lib/i686

      • Solaris: $JAVA_HOME/jre/lib/sparcv9

    • JVM_SO_HOME: Directory that contains libjvm.so; typically,

      • AIX: $JAVA_HOME/jre/lib/ppc64/j9vm

      • Linux: $JAVA_HOME/jre/lib/amd64/server, $JAVA_HOME/jre/lib/i386/server, or $JAVA_HOME/jre/lib/i686/server

      • Solaris: $JAVA_HOME/jre/lib/sparcv9/server

    +

    Although GTMJI may as well work on other combinations of platforms and Java implementations, the above are the platforms on which GTMJI is tested. Versions of each platform are those on which your GT.M is supported per the release notes for that release.

    [Note]Download Examples

    gtmji-demo.zip contains examples of Java programs, call-in/call-out tables, and GT.M APIs described in this technical bulletin. To download gtmji-demo.zip, click Download gtmji-demo.zip or open directly from http://tinco.pair.com/bhaskar/gtm/doc/articles/gtmji-demo.zip. For instruction on running call-in examples, see the code comments of CI.java or JPiece.java. For instructions on running the call-out example, see the code comments of CO.java.

    Installation

    GTMJI comes with a Makefile that you can use with GNU make to build, test, install, and uninstall the package. On some platforms, GNU make may be accessed with the command gmake, not make. You can build and test GTMJI as a normal (non-root) user, and then as root install it as a GT.M plug-in. The targets in Makefile that are intended for external use are

    • all: creates libgtmj2m.so and libgtmm2j.so (shared libraries of C code that acts as a gateway for Java call-ins and call-outs, respectively) and gtmji.jar (a Java archive containing GTMJI type wrapper and thread management classes).

    • clean: deletes all files created as a result of running the test and/or all target.

    • install: executed as root, installs GTMJI as a plug-in under the GT.M installation directory.

    • install-test: executed as root, ensures the operation of GTMJI after building and installation. Messages "GTMJI-INSTALL-SUCCESS: Call-ins test succeeded." and "GTMJI-INSTALL-SUCCESS: Call-outs test succeeded." confirm successful installation. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.

    • test: ensures the operation of GTMJI after building and before installation. As with the install-test target, "GTMJI-INSTALL-SUCCESS: Call-ins test succeeded." and "GTMJI-INSTALL-SUCCESS: Call-outs test succeeded." messages should appear. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.

    • uninstall: executed as root, removes the installed plug-in from under the GT.M installation directory.

    The following targets also exist but are intended for use within the Makefile rather than for external invocation: libgtmj2m.so, libgtmm2j.so, gtmji.jar, $(PLUGINDIR)/libgtmj2m.so, $(PLUGINDIR)/libgtmm2j.so, $(PLUGINDIR)/gtmji.jar, $(UTFPLUGINDIR)/libgtmj2m.so, $(UTFPLUGINDIR)/libgtmm2j.so, and $(UTFPLUGINDIR)/gtmji.jar.

    To run the Makefile, set the following environment variables:

    • gtm_dist: Installation directory of GT.M that contains libgtmshr.so and such include files as gtm_common_defs.h and gtmxc_types.h. If you plan to install GTMJI for multiple GT.M versions, please clean the build each time, since both gtmxc_types.h and gtm_common_defs.h are included from $gtm_dist to build the shared library.

    • JAVA_HOME: Top directory of your Java installation, such as /usr/lib/jvm/jdk1.6.0_25.

    • JAVA_SO_HOME: Directory that contains libjava.so; typically,

      • AIX: $JAVA_HOME/jre/lib/ppc64

      • Linux: $JAVA_HOME/jre/lib/amd64, $JAVA_HOME/jre/lib/i386, or $JAVA_HOME/jre/lib/i686

      • Solaris: $JAVA_HOME/jre/lib/sparcv9

    • JVM_SO_HOME: Directory that contains libjvm.so; typically,

      • AIX: $JAVA_HOME/jre/lib/ppc64/j9vm

      • Linux: $JAVA_HOME/jre/lib/amd64/server, $JAVA_HOME/jre/lib/i386/server, or $JAVA_HOME/jre/lib/i686/server

      • Solaris: $JAVA_HOME/jre/lib/sparcv9/server

    Note that if you also have a GT.M installation with UTF-8 support (that is, GT.M executables under $gtm_dist/utf8), then you might need to configure a few additional environment variables for targets that run GTMJI tests, such as test and install-test. Setting gtm_icu_version suffices in most situations.

    The steps for a typical GTMJI installation are as follows:

    1. Set gtm_dist, JAVA_HOME, JAVA_SO_HOME, and JVM_SO_HOME environment variables.

    2. Run make all.

    3. Run make test. When make test completes, two (four if you have a UTF-8-enabled installation) "GTMJI-INSTALL-SUCCESS ..." messages get displayed.

    4. Run make install.

    5. Run make install-test. When make install-test completes, two (four if you have a UTF-8-enabled installation) "GTMJI-INSTALL-SUCCESS ..." messages get displayed.

    6. Run make clean to remove all temporary GTMJI files created in the current directory by other make commands.

    GT.M call-ins usage from Java

    Environment Configuration

    To call-in to GT.M application code from Java application code requires the gtmji.jar Java archive together with the libgtmj2m.so shared library. The JAR contains the definitions of special types that the call-in functions may use for arguments; it also loads the shared library, performs concurrency control, and sets up proper rundown logic on Java process termination. In addition to the usual GT.M environment variables, such as gtmroutines and gtmgbldir, the following environment variables need to be defined:

    • GTMCI: The location of the call-in table, as described in the GT.M Programmers Guide.

    • LD_LIBRARY_PATH (LIBPATH on AIX): Includes the location of libgtmj2m.so shared library, such as /usr/lib/fis-gtm/V6.0-002/plugin. Alternatively, pass the location of the shared library to the JVM via java.library.path property.

    After setting these environment variables, the invocation of a Java process might look like

    java -classpath "/path/to/classes/top/dir/:/path/to/gtmji.jar" com.callins.Test

    or

    java -Djava.library.path=/path/to/libgtmj2m/dir/ -classpath "/path/to/classes/top/dir/:/path/to/gtmji.jar" com.callins.Test

    in case you do not set LD_LIBRARY_PATH. It is also possible to define CLASSPATH environment variable instead of specifying the -classpath option.

    Invocations

    GTMJI provides the following methods for invoking M routines, each for a specific return type:

    public static native void doVoidJob(String routine, Object... args);     
diff --git a/articles/GTM_Database_Encryption.html b/articles/GTM_Database_Encryption.html
index 5a55acf..4f4666a 100644
--- a/articles/GTM_Database_Encryption.html
+++ b/articles/GTM_Database_Encryption.html
@@ -1495,7 +1495,7 @@ body {
 
    

    

   
    

-    

+    

   
    

 
    

 
    

@@ -1650,7 +1650,7 @@ body {
   The following schematic illustrates acquisition of the password for the key ring on disk.  Note that an error (for example from the entry of an incorrect password) may not be triggered immediately a?? for example, DSE does not need an encryption key until you attempt to access data (since the file header is not encrypted, access to it does not require a key).
    

       

   
    

-    

+    

   
    

   
    

       

@@ -1662,7 +1662,7 @@ body {
   
    

 
    

 
    

-  

+  

 
    

 
    

   

@@ -1747,7 +1747,7 @@ body {
      
    

     
    

     
    

-      

+      

     
    

     
    

   
    

@@ -1844,7 +1844,7 @@ body {
       
    

         
    

           
    

-            

+            

           
    

         
    

       
    

@@ -1856,7 +1856,7 @@ body {
     
    

       
    

         
    

-          

+          

         
    

         
    

       
    

@@ -1877,7 +1877,7 @@ body {
     
    

     

     
    

-      

+      

     
    

     
    

     
    

@@ -1893,7 +1893,7 @@ body {
 
    

 
    

 
    

-  
    

+  
    

   
    

      
    

   
    

@@ -2412,7 +2412,7 @@ body {
 
    

 
    

   
    

-    

+    

   
    

   
    

 
    

diff --git a/articles/GTM_Database_Migration.html b/articles/GTM_Database_Migration.html
index ee7beef..01e7464 100644
--- a/articles/GTM_Database_Migration.html
+++ b/articles/GTM_Database_Migration.html
@@ -57,7 +57,7 @@
          
  • Bring down all V4 GT.M processes and execute mupip rundown -file on each database file to ensure that there are no processes accessing the database files.
  • Take a backup of all the database files. Alternatively, use mupip journal -recover -forward to apply journal files to backups of database files taken above.  Note that this may involve multiple generations of journal files for each database file.  Archive journal files, if the policy is to archive journal files.
  • Use dbcertify certify to certify all the database files as being ready to be upgraded to V5 format.
  • Use V5 mupip upgrade to upgrade the database file header from V4 format to V5 format.
  • Recompile routines and rebuild shared libraries (can be done in parallel with the above).
  • Make copies of all global directory files. Use V5 GDE to open and exit each global directory to update it to V5 format. (This step is not needed when upgrading from V5 field test releases.)
  • Run dse maps -restore_all on the upgraded database. This will rebuild all the maps and reflect the blocks used in the database file. 
  • Resume normal GT.M applications with V5.
  • While GT.M V5 applications are in normal use, run V5 mupip reorg -upgrade to convert any V4 format blocks that may be read but may not be updated (e.g., history records) to V5 format.
    •

    Return to top

    Background

    At the heart of GT.M's transaction management capability is the "transaction number" (TN). Each index or data block has a "block transaction number" (BTN) field. At each database update, the BTN field of all the altered blocks has the "current transaction number" (CTN) recorded within it. When a process references a block, by comparing the BTN with the BTN the last time it referenced that block, the process can determine whether the block has changed or not. Having a monotonically increasing CTN for the database, and being able to compare this with the BTNs is therefore crucial to being able to maintain consistency and structural integrity of the database during normal operation with hundreds or thousands of concurrent processes simultaneously updating the database.

    For all GT.M releases through the V4 series[1], the TN was an unsigned 32-bit integer, which meant that the maximum transaction number was 4,294,967,295. Before the maximum transaction number was reached, a database had to have all of its BTNs reset with a mupip integ -tn_reset command (see Chapter 6 of the GT.M Administration and Operations manual), a procedure that requires stand-alone access to the database, and which can take several hours on a large production database. GT.M was not very user friendly in that while a MUPIP INTEG would generate a warning when the CTN was within approximately 300 million of the limit (i.e., more than 93% of the TN range was used), normal operation would not generate any warning. Causing the transaction number to wrap around could damage the database.

    Furthermore, as computer systems have become faster, production databases at large financial institutions would require a TN RESET every few months. Unless logical dual site operation of an application is implemented, a TN RESET requires that the GT.M based application not be available for those few hours.

    Effective GT.M V5.0-000, the TN becomes an unsigned 64-bit number with a maximum value of 18,446,744,073,709,551,615. This means that if a financial institution needs an annual TN reset with GT.M V4, it would need a TN reset every 4,294,967,295 years with GT.M V5. A transaction processing application that runs flat out at a non-stop rate of 1,000,000 updates per second would need a TN reset approximately every 584,554 years. Thus, a 64-bit TN simplifies the operational management of a GT.M application.

    Since V4 databases only reserve 32-bits of space for TNs, the GT.M V5 database format is different from the V4 format (hence the need to change the major software version number from V4 to V5, as in V4.4-004 to V5.0-000), and a database upgrade is required when migrating from GT.M V4 to GT.M V5. In V5.0-000, the block header requires 16 bytes, vs. 8 bytes in all prior releases, through V5.0-FT02. This means that any prior database file that has even a single block that contains a single record that is larger than sixteen bytes less than the block size will require a database file with larger block size in V5.0-000.

    The traditional way to migrate a database is to perform a MUPIP EXTRACT with GT.M V4, and a MUPIP LOAD of the extracted data with GT.M V5. However, this approach requires that the database file be unavailable for the time that it takes to extract and load - potentially several hours - during which the application is not available, unless the application is deployed in a logical dual site configuration.

    GT.M V5.0 therefore provides an alternative mechanism to upgrade the database, one that allows most operations to be performed while the database is in use, and reduces the required time that the database is unavailable to - in the typical case - seconds to minutes.

    Also, for those who wish to try GT.M V5 before they switch to it, GT.M V5.0-000 has the ability to run with a database format that can almost instantaneously be switched to a V4 format, albeit with some impact on performance when using this feature.

    In order to accommodate 64-bit TNs, there are changes to the database file header, as well as to each database index and data block. In order to facilitate a database migration approach that minimizes the amount of time that an application must be unavailable, there are additional fields to support an in-place upgrade.

    [Note]

    A further enhancement effective V5.0-000 is that the maximum database file size is 134,217,728 (128M) blocks, whereas in all prior releases, through GT.M V5.0-FT02, the maximum database file size is 67,108,864 (64M) blocks. V4 databases that are upgraded to V5 retain the maximum database file size limit of 64M blocks (which means that with the popular 4KB block size, a single database file can grow to a maximum size of 256GB).

    Database File Header Changes

    There are a number of changes to the database file header, and these are reflected in the output of the dse dump -fileheader command, as described below:

    1. All transaction number fields (including CTN) are increased in size from 32 bits to 64 bits.

    2. Master Bitmap Size - since the master bitmap size is different for databases created with V5, compared to those upgraded from V4, the master bitmap size is made explicit and visible.

    3. Blocks to Upgrade - in order to support an incremental upgrade, there is a count of the blocks in the database that are still in V4 format.

    4. Desired DB format - for an option to "try before you switch", as well as an incremental database downgrade for those wishing to migrate a database from V5 to V4, there is a field that specifies the format of database blocks that are written out to the database file.

    5. Certified for Upgrade to - in order to accomplish the incremental upgrade, a database must be "pre-certified" using a new dbcertify utility that certifies that a database is ready for an incremental upgrade.

    6. "Hard Stop" transaction number - even if a database is in V5 format with a maximum transaction number of 264 - 1, for users who wish to preserve the ability to downgrade to V4, where the maximum transaction number cannot exceed 232-1, there is a "hard stop" TN. In order to support journal recovery and rollback for databases in V4 format, this needs to be 232-1-128M, or 4,160,749,567 (0xF7FFffff). For a database in V5 format, this needs to be 264-1-256M or 18,446,744,073,441,116,159 (0xFFFFffffEFFFffff)

    7. "Warning" transaction number - when the transaction number crosses this limit, GT.M will generate a warning, and update the warning transaction number to a new value. The new warning TN will be 256M (128M for a database with a Desired db format of V4) greater than the current warning TN unless the current warning TN is within 256M (128M for a Desired db format of V4) of the Hard Stop TN, in which case the new Warning TN will be halfway between the old Warning TN and the Hard Stop TN (so that the frequency of warnings will increase as the Hard Stop TN is approached).

    -

    The layout of the database file header has also changed, but this is not of any consequence to users since the only way to interact with the database file header is via the dse change -fileheader and mupip set commands.

    Block Format Changes

    Every V5 format database and index block requires a 64-bit BTN. Furthermore, since a database can have both V4 and V5 format blocks within it, there is a need to distinguish between V4 format blocks and V5 format blocks.

    The V4 block header is 8 bytes on UNIX, 7 bytes on OpenVMS, and is laid out as follows:

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 4 bytes - BTN

    In V5, the block header is increased to 16 bytes, and is laid out as follows:

    • 2 bytes - block version number

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 8 bytes - BTN

    If the value in the first two bytes is 0 through 6, GT.M V5 knows that the block is a V5 block and the field is a block version number; if it is 7 or greater, GT.M V5 knows that it is a V4 block and the field is the number of bytes currently in use in the block. This feature - a true hack - permits a GT.M database to contain both V4 format blocks as well as V5 format blocks, and facilitates the incremental upgrading of V4 databases to V5 with minimal unavailability of applications.

    One result of the fact that GT.M V5 has a 16-byte block header, whereas GT.M V4 has a 7 or 8 byte block header is that it is possible to have a record in a V4 database that will not fit in a V5 database with the same block size. The largest record that can fit in a V4 GT.M database on x86 GNU/Linux with a 4KB block size is 4088 bytes, whereas the largest record that can fit in a V5 GT.M database on the same platform is 4080 bytes. If there are any records whose size exceeds blocksize-16, then a new V5 database will need to be created with a larger block size. [2]

    Approaches to Migration

    Common to all Approaches
    Global Directory

    Since GT.M V5 adds support for names longer than 8 characters (see GT.M Long Names Technical Bulletin), as well as optional changes to the collation of null subscripts (see GT.M Null Subscripts Technical Bulletin), the V5 global directory format is different from a V4 global directory format, and must be upgraded.

    Please refer to the V5.0-000D Release Notes to upgrade the global directory.

    [Note]

    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Journal files and backups

    Journal files are specific to each GT.M version, and a journal file generated by one GT.M version is not compatible with another GT.M version. In particular, GT.M V4.4-004 journal files can only be processed by V4.4-004 and cannot be processed by V5.0-000. This means that a successful database backup as of the point of conversion is strongly recommended.

    [Note]

    An online backup that allows the application to continue operating will not suffice for such a backup, since a GT.M mupip backup command creates a snapshot of the database as of the instant that the command is issued, and not as of the time that the command completes.

    [Tip]

    mupip backup for a large database, even with the -bytestream flag, can take a non-trivial amount of time to run, perhaps more time than one might desire that the application be unavailable. An alternative approach is to take the journal files when the application is brought down, immediately prior to a database upgrade, and to apply them to a database backup from an earlier time with a mupip journal -recover -forward command, which should be faster than a mupip backup command.

    Logical Dual Site Operation

    A GT.M application that is configured for logical dual site operation can be upgraded from V4 to V5 while maintaining continuity of application availability. Please follow the procedures in the Database Replication chapter of the GT.M Administration and Operations Guide. Note that V4 journal files and mupip backup -bytestream files are not compatible with V5.

    Traditional

    The traditional approach to upgrading a database file is to extract it on the lower GT.M version with a mupip extract and to load it on the higher GT.M version with mupip load. Both BINARY format (mupip extract -format=binary) as well as the default ZWR format will work; however, the former is likely to be faster.

    Since the V4 database files are not modified with this approach, they can simply be archived, and a separate backup is not needed. The mupip extract files can also serve as an alternative backup.

    The benefits of a traditional approach are its simplicity and the fact that a database created with GT.M V5.0-000 can grow to a maximum size of 134,217,728 (128M) blocks, whereas a database created with a GT.M V4 release and upgraded to V5 retains a maximum size of 67,108,864 (64M) blocks.

    In-place upgrade minimizing down time

    Since a database extract and reload can take hours for large database files, GT.M V5.0-000 provides a method to upgrade database files that, at least in the typical case, requires that the application be brought down for only seconds to minutes. The basic approach to the in-place upgrade is the ability of GT.M V5.0-000 to read database blocks in V4 or V5 format. Whenever a block is updated, it will be written in V5 format. Thus, over time, the blocks are converted from V4 format to V5 format. Conceptually, this is a three-step process:

    1. Test and Certify: Test whether a database qualifies for an in-place upgrade, and certify it if it is. Except for a small part at the end, which in the typical case is expected to take only seconds to minutes, this step can be performed while the application is operating normally.

    2. Upgrade Database File Header: Upgrade the database file header from V4 format to V5 format. This requires stand-alone access of at most a few seconds.

    3. Use Applications Normally: Use the application normally with GT.M V5: When a database block is read in from disk to the global buffer cache, it is converted from V4 format to V5 format. Any V4 format blocks that are updated are automatically converted to V5 format. Since some database blocks may never be updated under normal operation (e.g., history records), a mupip reorg -upgrade command can be executed in the background to update all V4 format blocks to V5 format blocks.

    Test and Certify

    The critical requirement for being able to upgrade a database from V4 format to V5 format, whether in place or traditional, is that there must be no blocks whose records occupy more than blocksize-16 bytes. This is because database blocks in the global buffer cache are always in V5 format - when GT.M V5 reads a V4 format block into the global buffer cache, it converts it to V5 format. When writing out blocks, they can be written out in V5 format or converted to V4 format. If a database has no blocks with records occupying more than blocksize-16 bytes, upgrading to V5 is a snap. If it does have such blocks, they will need to be dealt with.

    There are two types of blocks whose records occupy more than blocksize-16 bytes - those with one record and those with more than one record. The latter can be made suitable for upgrading to V5 format blocks simply by splitting the block, but the former cannot: if a database contains even one block with one record which is larger than blocksize-16 bytes, that database cannot be upgraded in place from V4 to V5. Such a database file will require a new database to be created in V5 with a larger block size, following which the data must be extracted in V4 and loaded in V5.

    The dbcertify program is used to scan a V4 database and identify blocks with more than blocksize-16 bytes occupied. The testing and certification process has several steps:

    1. Increase the Reserved Bytes parameter in the database file header by 8 (UNIX/Linux) or 9 (OpenVMS). Note that the Reserved Bytes field is typically zero, so the new values will typically be 8 (UNIX) or 9 (OpenVMS). However, your database files may not be typical, so always check the value of this field with dse dump -fileheader and increment the value accordingly. This will ensure that no new records are created with a record size greater than blocksize-16, even though existing records will remain unaltered. You can run a mupip reorg on the database after setting Reserved Bytes to the new value; this will reduce the number of blocks that dbcertify will need to deal with in the next step.

    2. Verify that the Maximum Record Size parameter is less than or equal to blocksize-16, which it must be in V5. If it is not, you must determine whether your application requires it to be greater than blocksize-16, in which case a database upgrade is not possible: you will need to create a new database in V5 with a larger block size, into which you can load data extracted from the V4 database. If the application permits the Maximum Record Size parameter to be reduced to be less than or equal to blocksize-16, then reduce it accordingly. Once the Maximum Record Size parameter is less than or equal to blocksize-16, dbcertify can be used.

    3. The dbcertify program has two phases, a scan phase and a certify phase. Fidelity strongly recommends a backup before the certify phase, refer to the Tip in the Journal Files and Backups section for a suggestion on how to obtain a fast backup. +

      The layout of the database file header has also changed, but this is not of any consequence to users since the only way to interact with the database file header is via the dse change -fileheader and mupip set commands.

    Block Format Changes

    Every V5 format database and index block requires a 64-bit BTN. Furthermore, since a database can have both V4 and V5 format blocks within it, there is a need to distinguish between V4 format blocks and V5 format blocks.

    The V4 block header is 8 bytes on UNIX, 7 bytes on OpenVMS, and is laid out as follows:

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 4 bytes - BTN

    In V5, the block header is increased to 16 bytes, and is laid out as follows:

    • 2 bytes - block version number

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 8 bytes - BTN

    If the value in the first two bytes is 0 through 6, GT.M V5 knows that the block is a V5 block and the field is a block version number; if it is 7 or greater, GT.M V5 knows that it is a V4 block and the field is the number of bytes currently in use in the block. This feature - a true hack - permits a GT.M database to contain both V4 format blocks as well as V5 format blocks, and facilitates the incremental upgrading of V4 databases to V5 with minimal unavailability of applications.

    One result of the fact that GT.M V5 has a 16-byte block header, whereas GT.M V4 has a 7 or 8 byte block header is that it is possible to have a record in a V4 database that will not fit in a V5 database with the same block size. The largest record that can fit in a V4 GT.M database on x86 GNU/Linux with a 4KB block size is 4088 bytes, whereas the largest record that can fit in a V5 GT.M database on the same platform is 4080 bytes. If there are any records whose size exceeds blocksize-16, then a new V5 database will need to be created with a larger block size. [2]

    Approaches to Migration

    Common to all Approaches
    Global Directory

    Since GT.M V5 adds support for names longer than 8 characters (see GT.M Long Names Technical Bulletin), as well as optional changes to the collation of null subscripts (see GT.M Null Subscripts Technical Bulletin), the V5 global directory format is different from a V4 global directory format, and must be upgraded.

    Please refer to the V5.0-000D Release Notes to upgrade the global directory.

    [Note]

    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Journal files and backups

    Journal files are specific to each GT.M version, and a journal file generated by one GT.M version is not compatible with another GT.M version. In particular, GT.M V4.4-004 journal files can only be processed by V4.4-004 and cannot be processed by V5.0-000. This means that a successful database backup as of the point of conversion is strongly recommended.

    [Note]

    An online backup that allows the application to continue operating will not suffice for such a backup, since a GT.M mupip backup command creates a snapshot of the database as of the instant that the command is issued, and not as of the time that the command completes.

    [Tip]

    mupip backup for a large database, even with the -bytestream flag, can take a non-trivial amount of time to run, perhaps more time than one might desire that the application be unavailable. An alternative approach is to take the journal files when the application is brought down, immediately prior to a database upgrade, and to apply them to a database backup from an earlier time with a mupip journal -recover -forward command, which should be faster than a mupip backup command.

    Logical Dual Site Operation

    A GT.M application that is configured for logical dual site operation can be upgraded from V4 to V5 while maintaining continuity of application availability. Please follow the procedures in the Database Replication chapter of the GT.M Administration and Operations Guide. Note that V4 journal files and mupip backup -bytestream files are not compatible with V5.

    Traditional

    The traditional approach to upgrading a database file is to extract it on the lower GT.M version with a mupip extract and to load it on the higher GT.M version with mupip load. Both BINARY format (mupip extract -format=binary) as well as the default ZWR format will work; however, the former is likely to be faster.

    Since the V4 database files are not modified with this approach, they can simply be archived, and a separate backup is not needed. The mupip extract files can also serve as an alternative backup.

    The benefits of a traditional approach are its simplicity and the fact that a database created with GT.M V5.0-000 can grow to a maximum size of 134,217,728 (128M) blocks, whereas a database created with a GT.M V4 release and upgraded to V5 retains a maximum size of 67,108,864 (64M) blocks.

    In-place upgrade minimizing down time

    Since a database extract and reload can take hours for large database files, GT.M V5.0-000 provides a method to upgrade database files that, at least in the typical case, requires that the application be brought down for only seconds to minutes. The basic approach to the in-place upgrade is the ability of GT.M V5.0-000 to read database blocks in V4 or V5 format. Whenever a block is updated, it will be written in V5 format. Thus, over time, the blocks are converted from V4 format to V5 format. Conceptually, this is a three-step process:

    1. Test and Certify: Test whether a database qualifies for an in-place upgrade, and certify it if it is. Except for a small part at the end, which in the typical case is expected to take only seconds to minutes, this step can be performed while the application is operating normally.

    2. Upgrade Database File Header: Upgrade the database file header from V4 format to V5 format. This requires stand-alone access of at most a few seconds.

    3. Use Applications Normally: Use the application normally with GT.M V5: When a database block is read in from disk to the global buffer cache, it is converted from V4 format to V5 format. Any V4 format blocks that are updated are automatically converted to V5 format. Since some database blocks may never be updated under normal operation (e.g., history records), a mupip reorg -upgrade command can be executed in the background to update all V4 format blocks to V5 format blocks.

    Test and Certify

    The critical requirement for being able to upgrade a database from V4 format to V5 format, whether in place or traditional, is that there must be no blocks whose records occupy more than blocksize-16 bytes. This is because database blocks in the global buffer cache are always in V5 format - when GT.M V5 reads a V4 format block into the global buffer cache, it converts it to V5 format. When writing out blocks, they can be written out in V5 format or converted to V4 format. If a database has no blocks with records occupying more than blocksize-16 bytes, upgrading to V5 is a snap. If it does have such blocks, they will need to be dealt with.

    There are two types of blocks whose records occupy more than blocksize-16 bytes - those with one record and those with more than one record. The latter can be made suitable for upgrading to V5 format blocks simply by splitting the block, but the former cannot: if a database contains even one block with one record which is larger than blocksize-16 bytes, that database cannot be upgraded in place from V4 to V5. Such a database file will require a new database to be created in V5 with a larger block size, following which the data must be extracted in V4 and loaded in V5.

    The dbcertify program is used to scan a V4 database and identify blocks with more than blocksize-16 bytes occupied. The testing and certification process has several steps:

    1. Increase the Reserved Bytes parameter in the database file header by 8 (UNIX/Linux) or 9 (OpenVMS). Note that the Reserved Bytes field is typically zero, so the new values will typically be 8 (UNIX) or 9 (OpenVMS). However, your database files may not be typical, so always check the value of this field with dse dump -fileheader and increment the value accordingly. This will ensure that no new records are created with a record size greater than blocksize-16, even though existing records will remain unaltered. You can run a mupip reorg on the database after setting Reserved Bytes to the new value; this will reduce the number of blocks that dbcertify will need to deal with in the next step.

    2. Verify that the Maximum Record Size parameter is less than or equal to blocksize-16, which it must be in V5. If it is not, you must determine whether your application requires it to be greater than blocksize-16, in which case a database upgrade is not possible: you will need to create a new database in V5 with a larger block size, into which you can load data extracted from the V4 database. If the application permits the Maximum Record Size parameter to be reduced to be less than or equal to blocksize-16, then reduce it accordingly. Once the Maximum Record Size parameter is less than or equal to blocksize-16, dbcertify can be used.

    3. The dbcertify program has two phases, a scan phase and a certify phase. Fidelity strongly recommends a backup before the certify phase, refer to the Tip in the Journal Files and Backups section for a suggestion on how to obtain a fast backup.

      1. The scan phase runs concurrently with normal operation of GT.M V4. It makes no modifications to the database, but instead produces a report of blocks that are too large to be used by GT.M V5.

      2. The certify phase requires stand-alone access to the database. An M program is provided with GT.M V5.0-000, V5CBSU, which can run concurrently with normal operation of GT.M V4 applications, and which can take the output of the dbcertify scan phase and help reduce the amount of work the certify phase must perform. This reduces the amount of time that dbcertify requires stand-alone access to the database.

    Once the certify phase of dbcertify completes, mupip upgrade can be used to upgrade the database file header.

    [Note]

    dbcertify assumes that there is no structural damage to the database. Therefore, Fidelity strongly recommends that a mupip integ (without the -fast switch) be performed on the database or a backup copy of the database as soon as possible prior to running dbcertify, and not to start dbcertify if there are any unusual events or unusual messages in the operator log after the mupip integ operation (or the backup operation that created the backup on which mupip integ was run).

    [Note]

    The dbcertify certify and mupip upgrade steps are not journaled and are not interruptible. In the event of a hardware or software malfunction in the dbcertify or mupip upgrade, the V4 database will need to be restored from a backup.

    [Note]

    Although dbcertify and V5CBSU are written to have minimal impact on running applications, the fact that they perform IO means that the impact will not be zero. Whether or not the impact is noticeable depends on the extent to which IO is limiting throughput on your system.

    Upgrade Database File Header

    Once the certify phase of dbcertify has completed, the database file header can be upgraded from V4 to V5 with mupip upgrade, an operation that should take a fraction of a second on even the largest databases, since it only affects the file header. Once the database file header has been upgraded, the database can be used by GT.M V5 processes.

    A GT.M V5 database has a switch in the file header that specifies whether blocks that are updated are written to the database in V4 format or V5 format. Mupip upgrade will set the switch to cause GT.M V5 processes to write updated blocks in V5 format. To cause GT.M V5 processes to write updated blocks in V4 format, an option which preserves the ability to revert to GT.M V4 on short notice, use a subsequent mupip set -version=v4 command.

    [Note]

    Using GT.M V4 blocks in GT.M V5 will incur a small performance penalty, which may or may not be noticeable depending on what is limiting the throughput of your system.

    [Note]

    Mupip upgrade will reduce the Reserved Bytes field in the database file header by 8 bytes (UNIX) or 9 bytes (OpenVMS).

    Use Applications Normally

    Once the database file header has been upgraded, the database can be used normally with GT.M V5 processes. With the default database file header upgrade, any database blocks that are updated are written in V5 format, so that over time an increasing percentage of the blocks will be in V5 format.

    Since there may be blocks in V4 format that are never updated (e.g., history records), and as long as they are in V4 format, every read will incur at least a slight performance penalty, mupip reorg -upgrade can be used in the background to convert these blocks to V5 format.

    Memory Mapped (MM) access method database files

    To upgrade a database file used with the MM access method (supported on OpenVMS only), it must either have its access mode changed to Buffered Global (BG) to use the upgrade method that minimizes access time, or the traditional upgrade method should be used.

    [Note]

    Changing the access method from MM to BG requires stand-alone access and is accomplished by the mupip set command.

    Reverting from V5 to V4

    It is feasible to revert from GT.M V5 to V4. The database must first be downgraded to V4 format before it can be accessed by a GT.M V4 release. This is accomplished with the steps below, assuming that the CTN of the database is less than 4,294,967,295 (0xFFFFFFFF). If the CTN exceeds this number, a mupip integ -tn_reset must first be performed, or the database must be extracted using V5 mupip extract (with the default ZWR format) and loaded with V4 mupip load into a database created with V4 mupip create.

    1. The following steps can take place during normal operation of GT.M V5 processes.

      1. Use mupip set -version=v4 so that any blocks that are updated are written in V4 format.

      2. Use mupip reorg -downgrade to convert all blocks from V5 format to V4 format.

      diff --git a/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html b/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html index 45d2c44..448952a 100644 --- a/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html +++ b/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html @@ -745,7 +745,7 @@ body {

      -
      +


      @@ -757,7 +757,7 @@ body {

      -
      +


      diff --git a/articles/GTM_Multi_Site_Replication.html b/articles/GTM_Multi_Site_Replication.html index 1813471..128384d 100644 --- a/articles/GTM_Multi_Site_Replication.html +++ b/articles/GTM_Multi_Site_Replication.html @@ -42,7 +42,7 @@ gtmsupport@fnf.com

    -

    Table of Contents

    Overview
    Summary
    User Interface
    Replication Instance File
    MUPIP REPLIC –INSTANCE_CREATE –NAME
    -INSTSEC[ONDARY] qualifier
    -ROOT[PRIMARY] and –PROPAGATE[PRIMARY] Qualifiers
    Obsolete –UPDATE Qualifier
    MUPIP REPLIC –SOURCE –START
    MUPIP REPLIC –RECEIVER –START
    MUPIP REPLIC –SOURCE –ACTIVATE
    MUPIP REPLIC –SOURCE –DEACTIVATE
    Starting up an instance
    Shutting down an instance
    Primary and Secondary transitions
    Refreshing secondary from backup of primary
    Lost transaction processing
    MUPIP REPLIC –SOURCE –NEEDREST[ART]
    MUPIP REPLIC –SOURCE –LOSTTN[COMPLETE]
    MUPIP REPLIC –EDIT[INSTANCE]
    MUPIP REPLIC -SOURCE –JNLPOOL
    DSE DUMP -FILE[HEADER]
    DSE CHANGE -FILE[HEADER]
    MUPIP JOURNAL -ROLLBACK
    MUPIP BACKUP
    Rolling Upgrade
    From a GT.M Dual-site version to a GT.M Multi-site version
    Error Messages
    Typographical Conventions

    GT.M V5.1-000 provides the capability to deploy an application in a logical multi-site configuration with multiple secondary sites to a single primary site.

    Prior versions of GT.M featured the capability to deploy an application in a logical dual-site configuration with only one secondary site.

    A configuration having a primary and secondary in proximity for operational efficiency, however, would not provide protection against a disruption that affects both systems. A separate and distant "disaster recovery" (DR) third system can provide the operational convenience of proximal systems for routine operations, and a distant system for continuity of business in the face of catastrophic events. Prior GT.M versions did not make it possible to set up multiple secondary and/or tertiary systems. GT.M V5.1-000 enables such multi-site configurations. For migration to the new version with continuity of business, a dual-site configuration where one site runs on a GT.M version that has multi-site replication enabled and the other site runs on a GT.M version that does not, is supported.

    [Note]

    The terms site and instance are used interchangeably throughout this technical bulletin to refer to a primary or secondary system that participates in replication. Please also note that GT.M imposes no restrictions on the number of instances that can reside on a given machine.

    [Note]

    A configuration that uses GT.M replication between one primary and one secondary is henceforth termed a dual-site configuration while a configuration that uses GT.M replication between one primary and more than one secondary and/or tertiaries is henceforth termed a multi-site configuration. Likewise, replication between one primary and one secondary is termed dual-site replication. Replication between one primary and more than one secondary and/or tertiaries is termed multi-site replication.

    GT.M V5.1-000 supports replication from one primary site to multiple secondary sites. As in prior versions of GT.M, at any given instant, only one primary instance performs updates. In GT.M V5.1-000, this primary can concurrently replicate to as many as sixteen (16) additional instances. Any of the secondary sites can become the new primary, in the event of an unplanned or planned outage of the primary.

    After recovering from the outage, the original primary becomes a secondary, potentially generating a lost transaction file to be sent to the new primary for (re)processing.

    The multi-site configuration capability permits a secondary instance to pass the transactions to a tertiary instance. The flow of transaction data is from the primary to the secondary to the tertiary. Herein, the secondary acts as a primary for the tertiary. Thus, if each of the 16 secondary instances were to feed 16 tertiary instances, there could be 273 instances (1 primary + 16 secondaries + 256 tertiaries). If the tertiary instances fed quaternary instances, there could be 4,369 instances (1 primary + 16 secondaries + 256 tertiaries + 4096 quaternaries). And so on.

    Any arbitrary reconfiguration of the instances would be feasible, as any instance in the tree of instances below the primary could potentially become a new primary, if the current primary comes down.

    [Note]

    A tree structure is required for replication and cycles are not supported.

    [Caution]

    Just because GT.M permits arbitrary reconfiguration of the instances, it does not mean that an application or a specific deployment of the application should permit such an arbitrary reconfiguration. Each application deployment should have a specific configuration and a strategy for dealing with unplanned and planned outages.

    To differentiate the real primary from the secondary that is also acting as a primary (for the tertiary), GT.M V5.1-000 introduces the notion of a root primary versus a propagating primary.

    The instance on which business logic is executed, and resulting database updates are computed & commited, is termed the root primary. The secondary that acts as a primary (to a tertiary) is termed a propagating primary. This can be further extended to allow the tertiary replicate to a quaternary and so on. In such a case, the tertiary also acts as a propagating primary. There can be any number of propagating primaries but only ONE root primary in GT.M V5.1-000.

    GT.M process updates to replicated regions are disabled on all instances except the root primary (note that mupip reorg and database repair in the unlikely event of structural database damage needing repair with DSE, are not considered logical updates, and are permitted on the secondary). To identify whether the current instance is a root primary or a propagating primary the source server startup command now has an optional qualifier, -rootprimary or -propagate primary.

    Central to multi-site replication support is the notion of an instance name. Each replication instance is uniquely identified by a name that can be from 1 to 15 alphanumeric characters. This name is stored in the replication instance file of that instance. The instance name uniquely identifies every site in the multi-site configuration, as each site has only one replication instance file.

    [Caution]

    The instance name should be unique and two instances should not have the same name.

    [Note]

    The instance name is not changeable once the instance has served the role of either a primary (root or propagating) or a secondary since the replication instance files of all the corresponding secondaries and/or primaries connected to the instance maintain a record of the instance name.

    Since there can be multiple source servers running (one per active secondary) on a primary instance, source server commands need to specify secondary instance names to identify specific source servers.

    As indicated previously, a secondary running on GT.M V5.1-000 is supported with a primary running a prior version of GT.M and vice versa, which will occur in a rolling upgrade. Multiple secondary instances are allowed only after both the primary and secondary have been upgraded to GT.M V5.1-000. Likewise, tertiaries are allowed from a secondary only after both the primary and secondary have been upgraded to GT.M V5.1-000.

    [Note]

    Additional features of multi-site replication are available only when both the sites in an existing dual-site configuration are upgraded to GT.M V5.1-000.

    Return to top

    User Interface

    The changes to the user interface in V5.1-000 apply in both multi-site and dual-site configurations (e.g., if an instance name is required by a command, it is required even when operating in a dual-site configuration.

    Return to top

    Replication Instance File

    In order to use replication in dual-site or multi-site mode on UNIX, new replication instance files need to be created. A REPLINSTFMT error occurrs if a replication instance file from a previous version of GT.M is used. A FILENOTFND error occurs if the instance file does not exist and replication is attempted.

    The name given at the time of creating the instance file uniquely identifies the instance and is stored in the replication instance file.

    The instance file serves as a repository of the history of the journal sequence numbers that are generated locally or received from other instances. The history is maintained as a set of records. Every record identifies a range of journal sequence numbers and the name of the root primary instance that generated those journal records. The first history record starts with the current journal sequence number of the instance. When a root primary and secondary communicate, the primary instance name is recorded in the replication instance file history of both the primary and the secondary as the instance that generated the transmitted journal sequence numbers. When a tertiary connects to a secondary, it is still the root primary instance name (not that of the secondary which serves as a propagating primary) that gets recorded in the tertiary instance file since that is the instance that actually generated the records. History records are always added to the tail of the instance file, the only exception being records removed from the tail of the instance file when updates are rolled back from the database as part of a mupip journal –rollback.

    This history is crucial to determining the journal sequence numbers through which both instances are synchronized when a primary and secondary (or secondary and tertiary) attempt to connect. This journal sequence number is determined by going back in the history of both the instance files and finding the earliest shared journal sequence number that was generated by the same root primary instance. The receiver server on the secondary continues with normal replication only if the shared journal sequence number determined above matches the current journal sequence number of the secondary instance. Otherwise, a mupip journal –rollback –fetchresync must be performed on the secondary to rollback the secondary to a common synchronization point from which the primary can transmit updates to allow it to catch up. To avoid a possible out-of-sync situation, it is advisable, and safe even if it is not strictly necessary, so it can be unconditionally scripted, to perform a mupip journal -rollback -fetchresync prior to starting any source servers on the secondary instance.

    Processes such as source servers, receiver server, and mupip rollback access this history. A REPLINSTNOHIST error message is generated if they attempt to look up a history record corresponding to a sequence number (for example, as part of a -rollback operation) that is less than the earliest sequence number recorded in the instance file.

    A replication instance file maintains the current state of the instance and it is necessary to take a backup of this file that is consistent with the snapshot of the database files in the backup. Mupip journal -backup allows for the backup of the instance files at the same time that it backs up the database files.

    The replication instance file on the primary stores the information pertaining to each secondary for which a source server is started and the journal sequence number that was last transmitted to that secondary. In prior versions of GT.M, this journal sequence number was maintained as Resync Seqno in the database file headers of all replicated regions and a dse dump -fileheader would display this information. With GT.M V5.1-000, this information is only available in the replication instance file and mupip replic –source –showbacklog command uses this information to display the backlogs for secondary instances.

    The instance file has 16 slots to store information pertaining to a maximum of 16 secondary instances. Initially, all the slots are unused. A source server replicating to a secondary for the first time utilizes an unused slot to store the information related to that secondary and any future source server process replicating to the same secondary will update this information.

    If an unused slot is not available, the first time the source server starts, the slot for the least recently started secondary is reused, assuming of course that the source server for the secondary is not alive, and the information that is previously stored in that slot is overwritten. Any subsequent mupip replic –source on the preempted secondary instance generates a REPLINSTSECNONE message.

    [Note]

    Preemption of slots is not an issue if the primary does not connect to more than 16 different secondaries throughout its lifetime.

    If the replication instance file is damaged or deleted, a new instance file must be created, and all secondaries downstream must be recreated from backups.

    Return to top

    MUPIP REPLIC –INSTANCE_CREATE –NAME

    An instance name must be specified when the replication instance file is being created using the –name qualifier in the command line.

    The name identifies the replication instance to other instances, and it is immutable.

    [Note]

    In this rare instance, a GT.M command from a prior version is not upward compatible in GT.M V5.1-000.

    If -name is not specified, mupip uses the environment variable gtm_repl_instname for the name. If that variable is not defined, the command issues a REPLINSTNMUNDEF error message. Using the environment variable allows pre-existing user replication scripts to run without any changes. Explicitly specifying the qualifier in the scripts improves clarity.

    The name can be from 1 to 15 characters. Specifying a name longer than 15 characters or an empty string will issue a REPLINSTNMLEN error message.

    If an instance file already exists, it is renamed with a timestamp suffix, and a new one is created. This behavior is similar to the manner in which GT.M renames existing journal files while creating new journal files.

    Creating an instance file requires standalone access. A REPLINSTSTNDALN message is issued if the instance file is being used (i.e. the journal pool for that instance exists), while attempting to (re)create that instance file.

    Return to top

    -INSTSEC[ONDARY] qualifier

    On a primary instance, a source server process runs for each secondary instance. The –instsecondary qualifier identifies the secondary instance to which a source server replicates the data. In GT.M V5.1-000, the following commands have been modified to include the –instsecondary qualifier. It is mandatory to specify the –instsecondary qualifier while issuing these commands.

    +

    Table of Contents

    Overview
    Summary
    User Interface
    Replication Instance File
    MUPIP REPLIC –INSTANCE_CREATE –NAME
    -INSTSEC[ONDARY] qualifier
    -ROOT[PRIMARY] and –PROPAGATE[PRIMARY] Qualifiers
    Obsolete –UPDATE Qualifier
    MUPIP REPLIC –SOURCE –START
    MUPIP REPLIC –RECEIVER –START
    MUPIP REPLIC –SOURCE –ACTIVATE
    MUPIP REPLIC –SOURCE –DEACTIVATE
    Starting up an instance
    Shutting down an instance
    Primary and Secondary transitions
    Refreshing secondary from backup of primary
    Lost transaction processing
    MUPIP REPLIC –SOURCE –NEEDREST[ART]
    MUPIP REPLIC –SOURCE –LOSTTN[COMPLETE]
    MUPIP REPLIC –EDIT[INSTANCE]
    MUPIP REPLIC -SOURCE –JNLPOOL
    DSE DUMP -FILE[HEADER]
    DSE CHANGE -FILE[HEADER]
    MUPIP JOURNAL -ROLLBACK
    MUPIP BACKUP
    Rolling Upgrade
    From a GT.M Dual-site version to a GT.M Multi-site version
    Error Messages
    Typographical Conventions

    GT.M V5.1-000 provides the capability to deploy an application in a logical multi-site configuration with multiple secondary sites to a single primary site.

    Prior versions of GT.M featured the capability to deploy an application in a logical dual-site configuration with only one secondary site.

    A configuration having a primary and secondary in proximity for operational efficiency, however, would not provide protection against a disruption that affects both systems. A separate and distant "disaster recovery" (DR) third system can provide the operational convenience of proximal systems for routine operations, and a distant system for continuity of business in the face of catastrophic events. Prior GT.M versions did not make it possible to set up multiple secondary and/or tertiary systems. GT.M V5.1-000 enables such multi-site configurations. For migration to the new version with continuity of business, a dual-site configuration where one site runs on a GT.M version that has multi-site replication enabled and the other site runs on a GT.M version that does not, is supported.

    [Note]

    The terms site and instance are used interchangeably throughout this technical bulletin to refer to a primary or secondary system that participates in replication. Please also note that GT.M imposes no restrictions on the number of instances that can reside on a given machine.

    [Note]

    A configuration that uses GT.M replication between one primary and one secondary is henceforth termed a dual-site configuration while a configuration that uses GT.M replication between one primary and more than one secondary and/or tertiaries is henceforth termed a multi-site configuration. Likewise, replication between one primary and one secondary is termed dual-site replication. Replication between one primary and more than one secondary and/or tertiaries is termed multi-site replication.

    GT.M V5.1-000 supports replication from one primary site to multiple secondary sites. As in prior versions of GT.M, at any given instant, only one primary instance performs updates. In GT.M V5.1-000, this primary can concurrently replicate to as many as sixteen (16) additional instances. Any of the secondary sites can become the new primary, in the event of an unplanned or planned outage of the primary.

    After recovering from the outage, the original primary becomes a secondary, potentially generating a lost transaction file to be sent to the new primary for (re)processing.

    The multi-site configuration capability permits a secondary instance to pass the transactions to a tertiary instance. The flow of transaction data is from the primary to the secondary to the tertiary. Herein, the secondary acts as a primary for the tertiary. Thus, if each of the 16 secondary instances were to feed 16 tertiary instances, there could be 273 instances (1 primary + 16 secondaries + 256 tertiaries). If the tertiary instances fed quaternary instances, there could be 4,369 instances (1 primary + 16 secondaries + 256 tertiaries + 4096 quaternaries). And so on.

    Any arbitrary reconfiguration of the instances would be feasible, as any instance in the tree of instances below the primary could potentially become a new primary, if the current primary comes down.

    [Note]

    A tree structure is required for replication and cycles are not supported.

    [Caution]

    Just because GT.M permits arbitrary reconfiguration of the instances, it does not mean that an application or a specific deployment of the application should permit such an arbitrary reconfiguration. Each application deployment should have a specific configuration and a strategy for dealing with unplanned and planned outages.

    To differentiate the real primary from the secondary that is also acting as a primary (for the tertiary), GT.M V5.1-000 introduces the notion of a root primary versus a propagating primary.

    The instance on which business logic is executed, and resulting database updates are computed & commited, is termed the root primary. The secondary that acts as a primary (to a tertiary) is termed a propagating primary. This can be further extended to allow the tertiary replicate to a quaternary and so on. In such a case, the tertiary also acts as a propagating primary. There can be any number of propagating primaries but only ONE root primary in GT.M V5.1-000.

    GT.M process updates to replicated regions are disabled on all instances except the root primary (note that mupip reorg and database repair in the unlikely event of structural database damage needing repair with DSE, are not considered logical updates, and are permitted on the secondary). To identify whether the current instance is a root primary or a propagating primary the source server startup command now has an optional qualifier, -rootprimary or -propagate primary.

    Central to multi-site replication support is the notion of an instance name. Each replication instance is uniquely identified by a name that can be from 1 to 15 alphanumeric characters. This name is stored in the replication instance file of that instance. The instance name uniquely identifies every site in the multi-site configuration, as each site has only one replication instance file.

    [Caution]

    The instance name should be unique and two instances should not have the same name.

    [Note]

    The instance name is not changeable once the instance has served the role of either a primary (root or propagating) or a secondary since the replication instance files of all the corresponding secondaries and/or primaries connected to the instance maintain a record of the instance name.

    Since there can be multiple source servers running (one per active secondary) on a primary instance, source server commands need to specify secondary instance names to identify specific source servers.

    As indicated previously, a secondary running on GT.M V5.1-000 is supported with a primary running a prior version of GT.M and vice versa, which will occur in a rolling upgrade. Multiple secondary instances are allowed only after both the primary and secondary have been upgraded to GT.M V5.1-000. Likewise, tertiaries are allowed from a secondary only after both the primary and secondary have been upgraded to GT.M V5.1-000.

    [Note]

    Additional features of multi-site replication are available only when both the sites in an existing dual-site configuration are upgraded to GT.M V5.1-000.

    Return to top

    User Interface

    The changes to the user interface in V5.1-000 apply in both multi-site and dual-site configurations (e.g., if an instance name is required by a command, it is required even when operating in a dual-site configuration.

    Return to top

    Replication Instance File

    In order to use replication in dual-site or multi-site mode on UNIX, new replication instance files need to be created. A REPLINSTFMT error occurrs if a replication instance file from a previous version of GT.M is used. A FILENOTFND error occurs if the instance file does not exist and replication is attempted.

    The name given at the time of creating the instance file uniquely identifies the instance and is stored in the replication instance file.

    The instance file serves as a repository of the history of the journal sequence numbers that are generated locally or received from other instances. The history is maintained as a set of records. Every record identifies a range of journal sequence numbers and the name of the root primary instance that generated those journal records. The first history record starts with the current journal sequence number of the instance. When a root primary and secondary communicate, the primary instance name is recorded in the replication instance file history of both the primary and the secondary as the instance that generated the transmitted journal sequence numbers. When a tertiary connects to a secondary, it is still the root primary instance name (not that of the secondary which serves as a propagating primary) that gets recorded in the tertiary instance file since that is the instance that actually generated the records. History records are always added to the tail of the instance file, the only exception being records removed from the tail of the instance file when updates are rolled back from the database as part of a mupip journal –rollback.

    This history is crucial to determining the journal sequence numbers through which both instances are synchronized when a primary and secondary (or secondary and tertiary) attempt to connect. This journal sequence number is determined by going back in the history of both the instance files and finding the earliest shared journal sequence number that was generated by the same root primary instance. The receiver server on the secondary continues with normal replication only if the shared journal sequence number determined above matches the current journal sequence number of the secondary instance. Otherwise, a mupip journal –rollback –fetchresync must be performed on the secondary to rollback the secondary to a common synchronization point from which the primary can transmit updates to allow it to catch up. To avoid a possible out-of-sync situation, it is advisable, and safe even if it is not strictly necessary, so it can be unconditionally scripted, to perform a mupip journal -rollback -fetchresync prior to starting any source servers on the secondary instance.

    Processes such as source servers, receiver server, and mupip rollback access this history. A REPLINSTNOHIST error message is generated if they attempt to look up a history record corresponding to a sequence number (for example, as part of a -rollback operation) that is less than the earliest sequence number recorded in the instance file.

    A replication instance file maintains the current state of the instance and it is necessary to take a backup of this file that is consistent with the snapshot of the database files in the backup. Mupip journal -backup allows for the backup of the instance files at the same time that it backs up the database files.

    The replication instance file on the primary stores the information pertaining to each secondary for which a source server is started and the journal sequence number that was last transmitted to that secondary. In prior versions of GT.M, this journal sequence number was maintained as Resync Seqno in the database file headers of all replicated regions and a dse dump -fileheader would display this information. With GT.M V5.1-000, this information is only available in the replication instance file and mupip replic –source –showbacklog command uses this information to display the backlogs for secondary instances.

    The instance file has 16 slots to store information pertaining to a maximum of 16 secondary instances. Initially, all the slots are unused. A source server replicating to a secondary for the first time utilizes an unused slot to store the information related to that secondary and any future source server process replicating to the same secondary will update this information.

    If an unused slot is not available, the first time the source server starts, the slot for the least recently started secondary is reused, assuming of course that the source server for the secondary is not alive, and the information that is previously stored in that slot is overwritten. Any subsequent mupip replic –source on the preempted secondary instance generates a REPLINSTSECNONE message.

    [Note]

    Preemption of slots is not an issue if the primary does not connect to more than 16 different secondaries throughout its lifetime.

    If the replication instance file is damaged or deleted, a new instance file must be created, and all secondaries downstream must be recreated from backups.

    Return to top

    MUPIP REPLIC –INSTANCE_CREATE –NAME

    An instance name must be specified when the replication instance file is being created using the –name qualifier in the command line.

    The name identifies the replication instance to other instances, and it is immutable.

    [Note]

    In this rare instance, a GT.M command from a prior version is not upward compatible in GT.M V5.1-000.

    If -name is not specified, mupip uses the environment variable gtm_repl_instname for the name. If that variable is not defined, the command issues a REPLINSTNMUNDEF error message. Using the environment variable allows pre-existing user replication scripts to run without any changes. Explicitly specifying the qualifier in the scripts improves clarity.

    The name can be from 1 to 15 characters. Specifying a name longer than 15 characters or an empty string will issue a REPLINSTNMLEN error message.

    If an instance file already exists, it is renamed with a timestamp suffix, and a new one is created. This behavior is similar to the manner in which GT.M renames existing journal files while creating new journal files.

    Creating an instance file requires standalone access. A REPLINSTSTNDALN message is issued if the instance file is being used (i.e. the journal pool for that instance exists), while attempting to (re)create that instance file.

    Return to top

    -INSTSEC[ONDARY] qualifier

    On a primary instance, a source server process runs for each secondary instance. The –instsecondary qualifier identifies the secondary instance to which a source server replicates the data. In GT.M V5.1-000, the following commands have been modified to include the –instsecondary qualifier. It is mandatory to specify the –instsecondary qualifier while issuing these commands.

        	mupip replic –source –start
    	mupip replic –source –deactivate
    	mupip replic –source –activate
diff --git a/articles/GTM_Triggers.html b/articles/GTM_Triggers.html
index 931c5a1..bbaa43d 100644
--- a/articles/GTM_Triggers.html
+++ b/articles/GTM_Triggers.html
@@ -873,7 +873,7 @@ A trigger definition file is a text file used for adding new triggers, modifying
     
    
       
    
         
    
-          
+          
         
    
         
    
       
    
@@ -1440,7 +1440,7 @@ A trigger definition file is a text file used for adding new triggers, modifying
 The following illustration shows the flow of control when the trigger is executed for Set ^CIN(ACN,1)="Paul|John, Doe, Johnny|". The initial value of ^CIN(ACN,1) is "Paul|Doe, John|" and ACN is set to "NY".   
    
 
    
 
    
-  
+  
 
    
 
    
  
    
@@ -1449,7 +1449,7 @@ A trigger definition file is a text file used for adding new triggers, modifying
 The following illustration shows the flow of control when the trigger is executed for Kill ^CIN(ACN,1). 
    
 
    
   
    
-    
+    
   
    
   
    
 
    
diff --git a/articles/GTM_V5.2-000B_Release_Notes.html b/articles/GTM_V5.2-000B_Release_Notes.html
index 493d1e4..73fa4a1 100644
--- a/articles/GTM_V5.2-000B_Release_Notes.html
+++ b/articles/GTM_V5.2-000B_Release_Notes.html
@@ -116,9 +116,9 @@
 					SET COMMAND GTM$DIST:GTMCOMMANDS.CLD
 				
    in GTMLOGIN.COM or other command file for each process which uses GT.M, you must execute this 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 will need to 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 to match the proper GTMCOMMANDS.CLD with the version of GT.M being used.
    Managing M mode and UTF-8 mode
    From the same source file, the GT.M V5.2-000B mumps process generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. GT.M V5.2-000B mumps process 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. GT.M V5.2-000B mumps process trigger an error if the object file was generated with a different setting of $gtm_chset/$ZCHset.
    M object modules must be generated with an environment that matches the run-time setting. As the GT.M product contains M utility programs, their object files must conform to this rule. In order to be able to use either, or both, M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 “flavors” of object modules exist and can be found in known locations (as described above). The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use – the same pattern should be considered for structuring application object code repositories.
    The following changes are made to the way in which V5.2-000 (and above) is installed.
    1. Most GT.M product executables (mumps, mupip, dse, lke, etc.) are in the parent directory, that is, environment variable gtm_dist.
    2. The object files for programs written in M (GDE, utilities) have two versions-- one compiled for functionality related to Unicode™ in the utf8 subdirectory, and one compiled for functionality not related to Unicode™ in the parent directory. Installing V5.2-000B generates both the versions of object files if ICU 3.5 is installed; otherwise it generates only the M mode object files.
    3. Both the parent directory and the utf8 subdirectory have files called mumps, mupip, dse, etc.  Those in the utf8 subdirectory are relative symbolic links to the executables in the parent directory (e.g., mumps is the symbolic link ../mumps).
    4. When the user sources the shell scripts gtmprofile or gtmcshrc, the behavior is as follows:
 				
      1. If environment variable gtm_chset is m, M or undefined, there are no changes to the environment from the previous versions.
      2. If environment variable gtm_chset is UTF-8,
-						
        1. $gtm_dist is set to the utf8 subdirectory (i.e, if GT.M is installed in /usr/local/gtm_V5.2-000B, $gtm_dist will be set to /usr/local/gtm_V5.2-000B/utf8).
        2. The last element of $gtmroutines will not be $gtm_dist as it is today, but will instead be $gtm_dist($gtm_dist/..) so that the source directory for GDE and the utilities are matched with the appropriate executables.
    Note on setting the environment variable TERM
    Users must set the environment variable TERM to a terminfo entry that 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 is being run.
    [Important]
    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal functions. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) manufacturer may also be able to help.

    Return to top

    Change History

    Return to top

    V5.2-000B

    The only fix released in V5.2-000B is:

    +

    1. $gtm_dist is set to the utf8 subdirectory (i.e, if GT.M is installed in /usr/local/gtm_V5.2-000B, $gtm_dist will be set to /usr/local/gtm_V5.2-000B/utf8).

    2. The last element of $gtmroutines will not be $gtm_dist as it is today, but will instead be $gtm_dist($gtm_dist/..) so that the source directory for GDE and the utilities are matched with the appropriate executables.

    Note on setting the environment variable TERM

    Users must set the environment variable TERM to a terminfo entry that 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 is being run.

    [Important]
    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal functions. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) manufacturer may also be able to help.

    Return to top

    Change History

    Return to top

    V5.2-000B

    The only fix released in V5.2-000B is:

    C9H04-002843 -

    This fix is marked with [V5.2-000B] in the subsequent sections.

    Return to top

    V5.2-000A

    Fixes and enhancements released in V5.2-000A are:

    +

    This fix is marked with [V5.2-000B] in the subsequent sections.

    Return to top

    V5.2-000A

    Fixes and enhancements released in V5.2-000A are:

    S9C08-002197
    S9C10-002243 @@ -230,7 +230,7 @@

    • [V5.2-000A] SET of global variables within a parenthesized list of targets where the global references use extended syntax containing one or more local variables now occurs properly when the local variables are defined or gives an appropriate UNDEF error when a local variable is undefined. In previous versions, even when the local variables were all defined, it used to give a message that did not specify the variable name (HPUX/AIX) or a segmentation fault (SIG-11). [Linux/Tru64/Solaris/AlphaVMS] (S9C08-002197)

    • [V5.2-000A] Output-only parameters of type char * and string * without pre-allocation now trigger the ZCNOPREALLOUTPAR error. Also see C9F09-002753.[UNIX] (S9C10-002243)

      Note that this change makes V5.2-000A not backward compatible for programs that use this feature. Although GT.M is normally fastidious with respect to maintaining backward compatibility, improvements in performance and robustness were judged to warrant an exception in this case.

    • [V5.2-000A] The pattern match operator no longer causes a process to hang if the pattern following the question-mark (?) is a string literal more than 6 characters long and the repetition count consists of a period (.) with no leading and trailing integer literals. (S9F01-002526)

    • [V5.2-000A] Unrecognized Intrinsic Functions and Intrinsic Special Variables and unrecognized deviceparameter constructions that are bypassed due to FALSE postconditionals no longer cause run-time errors. The error messages affected by this change are INVFCN, INVSVN, FNOTONSYS, SVNOSET, SVNONEW, DEVPARINAP, DEVPARUNK, DEVPARVALREQ. These errors still trigger error reports at compile time—for example "SET:0 $ZZZZ=1" continues to generate a compilation error— but no longer generates a run-time error. (S9F10-002572)

    • [V5.2-000A] Extensive testing validates that two argument $STACK() and ZSHOW “S” work properly. If $ECODE is null then the two argument $STACK() returns the same result as ZSHOW "S". The result differs only when $ECODE contains error information. Fidelity recommends applications reset $ECODE in their error handlers before restoring the normal flow of control. (S9F12-002579)

    • READ X:0 now leaves $TEST set in case the only character READ is a terminator. (S9F12-002582)

    • Certain cases of an untimed OPEN of the TCP device that would cause the process to spin in a tight loop no longer do so.(S9G09-002625)

    • READ *X:<timeout>now properly times out when the timeout is greater than 8 seconds. [Linux] (S9G11-002628)

    • [V5.2-000A] $zgetjpi(“”,”INVALID ARG”) now produces the BADJPIPARAM error rather than a segmentation fault (SIG-11). (S9G12-002632) [UNIX]

    • [V5.2-000A] Pre-allocation of xc_string_t is now allowed and is required for output-only parameters on external calls. Also see S9C10-002243. (S9G12-002634, C9F09-002753) [UNIX]

    • [V5.2-000A] ZSHOW "V" or ZWR when variables with "long" content no longer give a segmentation fault (SIG-11). This was fixed in V5.2-000 but the fix was not documented. (S9G12-002635)

    • - [V5.2-000A] $ZB now contains the correct value after a READ *. In particular, $ZB holds the full escape sequence after entry of an escape sequence when ESCAPE processing enabled. This was broken in GT.M V5.2-000. [AIX/Solaris/HPUX] (S9H02-002642)

    • [V5.2-000A] Exponents greater than 18 digits no longer result in a numeric evaluation of 0; for example in previous versions, WRITE +"1E12234567890123456789" produced 0. (S9F11-002573)

    • [V5.2-000A]The GT.M utilities and the mumps commands now use a space-dash (“ –“)combination to delimit/introduce a qualifier, which is standard UNIX usage, where they used to require only a dash ("-", which was not standard).

      [Warning]
      This will cause existing shell scripts that use the idiosyncratic dash-only form to break – they can be fixed by adding one or more spaces in front of any dash.

      This change allows the use of dashes in argument and qualifier values. [UNIX] (C9B04-001681)

    • [V5.2-000A] $ORDER() now returns the correct value even if the optional second argument is specified and contains a global reference. In such cases, previous versions used to perform the $ORDER() operation on the global reference in the second argument instead of the first.

      $REFERENCE is now set properly after a $ORDER() operation involving a global reference in the first or second argument. Previous versions used to set this incorrectly. For example $ORDER(^x(1)) used to incorrectly set $REFERENCE to ^x(1.00) instead of ^x(1). (C9B10-001744)

    • [V5.2-000A] $ORDER() now returns the correct value where the second argument is an extrinsic function that manipulates the first argument. In such cases, previous versions could give an incorrect result. For example, $ORDER(V(2,-1),$$ABC) where the extrinsic $$ABC() sets the node V(2,2) to 1 and quits with a value of 1 now returns a result of 2 where it used to incorrectly return a null string (""). Substituting ^V for V in the example demonstrates the change for global references. (C9B10-001765)

    • [V5.2-000A] $GET() with two arguments where both the arguments contain global references now sets the naked indicator correctly to the last global reference in the second argument. In cases where the first argument had a value, previous versions used to incorrectly set the naked indicator to that first argument. (C9B10-001767)

    • [V5.2-000A] The processing of SET commands with multiple targets and $Piece() / $Extract() now complies better with the M standard.

      GT.M now allows the $PIECE() and $EXTRACT functions as targets in a SET command that has a parenthesized, comma-separated list of targets. Previous versions disallowed this usage.

      When SET arguments have multiple parenthesized (set-left) targets and a target is used as a subscript in more than one item in the list of targets that follow, ALL the targets now use the before-SET value (not the after-SET value) in conformance to the M-standard. Previous versions of GT.M used the before-SET value only for the last such subscripted target item in the list and incorrectly used the after-SET value for all prior subscripted target items. For example, set a=0,(a,array1(a),array2(a))=2 now sets both array1(0) and array2(0) to 2 whereas previous versions of GT.M would set array2(0) to 2 and array1(2) (instead of array1(0)) to 2.

      If a SET target is of the form $PIECE(glvn,d,m,n) or $EXTRACT(glvn,m,n) GT.M now evaluates the right hand side of the Set even when m > n or n < 1. Previous versions of GT.M would not evaluate the right-hand-side of the SET which could result in the naked indicator not being set correctly. For example, set ^x=1,$piece(^a,";",3,2)=^b now correctly sets the naked indicator to point to the global ^b. Previous versions of GT.M set the naked indicator to ^x in this example. (C9C05-002003)

    • GT.M socket devices now allow up to the number of clients specified in the environment variable gtm_max_sockets. The default limit is 64, and there is an absolute maximum which at this point in human history exceeds your wildest dreams. $VIEW("MAX_SOCKETS") returns the current value. (C9C10-002149)

    • [V5.2-000A] ZWRITE with a range (n:m) no longer no longer occasionally fails with a segmentation fault (SIG-11). [AIX; Solaris] (C9D01-002239)

    • The maximum length for the argument to the ZSYSTEM command has increased to 4K bytes.[UNIX] (C9E09-002637)

    • [V5.2-000A] Messages and Recovery Procedures Manual is now current up to V5.2-000A. See http://www.fidelityinfoservices.com/user_documentation/V52AMsgRecProc/index.htm. (C9F07-002745)

    • OPEN of TCP device with an invalid address specification now gives an appropriate error rather than terminating the process. (C9G12-002808)

    • [V5.2-000A] Pattern match with multiple unbounded patterns where a lower bound after the first unbounded pattern is 7 (9 for V5.2-000) or more now gives the correct result. For example, in GT.M V5.2 (1.1?.n1"."9.n), and, in prior versions, (1.1?.n1"."7.n) incorrectly returned 1. (C9G12-002813)

    • [V5.2-000A] GT.M now reports complete error messages where in V5.2-000 utf-8 mode they were terminated at the first non-ASCII character. [HP-UX] (C9G12-002815)

    • [V5.2-000A] GT.M no longer inappropriately issues a GTM-E-GTMSECSHRSOCKET when it finds a socket conflict (usually because of an abandoned socket) for use in activating GTMSECSHR actions.[UNIX] (C9H03-002828)

    • [V5.2-000A] GT.M introduces a new deviceparameter called MOREREADTIME that applies to OPEN and USE commands for a SOCKET device. Except when a READ has a zero (0) timeout, MOREREADTIME specifies the time (in milliseconds) that a READ waits for input. + [V5.2-000A] $ZB now contains the correct value after a READ *. In particular, $ZB holds the full escape sequence after entry of an escape sequence when ESCAPE processing enabled. This was broken in GT.M V5.2-000. [AIX/Solaris/HPUX] (S9H02-002642)

    • [V5.2-000A] Exponents greater than 18 digits no longer result in a numeric evaluation of 0; for example in previous versions, WRITE +"1E12234567890123456789" produced 0. (S9F11-002573)

    • [V5.2-000A]The GT.M utilities and the mumps commands now use a space-dash (“ –“)combination to delimit/introduce a qualifier, which is standard UNIX usage, where they used to require only a dash ("-", which was not standard).

      [Warning]
      This will cause existing shell scripts that use the idiosyncratic dash-only form to break – they can be fixed by adding one or more spaces in front of any dash.

      This change allows the use of dashes in argument and qualifier values. [UNIX] (C9B04-001681)

    • [V5.2-000A] $ORDER() now returns the correct value even if the optional second argument is specified and contains a global reference. In such cases, previous versions used to perform the $ORDER() operation on the global reference in the second argument instead of the first.

      $REFERENCE is now set properly after a $ORDER() operation involving a global reference in the first or second argument. Previous versions used to set this incorrectly. For example $ORDER(^x(1)) used to incorrectly set $REFERENCE to ^x(1.00) instead of ^x(1). (C9B10-001744)

    • [V5.2-000A] $ORDER() now returns the correct value where the second argument is an extrinsic function that manipulates the first argument. In such cases, previous versions could give an incorrect result. For example, $ORDER(V(2,-1),$$ABC) where the extrinsic $$ABC() sets the node V(2,2) to 1 and quits with a value of 1 now returns a result of 2 where it used to incorrectly return a null string (""). Substituting ^V for V in the example demonstrates the change for global references. (C9B10-001765)

    • [V5.2-000A] $GET() with two arguments where both the arguments contain global references now sets the naked indicator correctly to the last global reference in the second argument. In cases where the first argument had a value, previous versions used to incorrectly set the naked indicator to that first argument. (C9B10-001767)

    • [V5.2-000A] The processing of SET commands with multiple targets and $Piece() / $Extract() now complies better with the M standard.

      GT.M now allows the $PIECE() and $EXTRACT functions as targets in a SET command that has a parenthesized, comma-separated list of targets. Previous versions disallowed this usage.

      When SET arguments have multiple parenthesized (set-left) targets and a target is used as a subscript in more than one item in the list of targets that follow, ALL the targets now use the before-SET value (not the after-SET value) in conformance to the M-standard. Previous versions of GT.M used the before-SET value only for the last such subscripted target item in the list and incorrectly used the after-SET value for all prior subscripted target items. For example, set a=0,(a,array1(a),array2(a))=2 now sets both array1(0) and array2(0) to 2 whereas previous versions of GT.M would set array2(0) to 2 and array1(2) (instead of array1(0)) to 2.

      If a SET target is of the form $PIECE(glvn,d,m,n) or $EXTRACT(glvn,m,n) GT.M now evaluates the right hand side of the Set even when m > n or n < 1. Previous versions of GT.M would not evaluate the right-hand-side of the SET which could result in the naked indicator not being set correctly. For example, set ^x=1,$piece(^a,";",3,2)=^b now correctly sets the naked indicator to point to the global ^b. Previous versions of GT.M set the naked indicator to ^x in this example. (C9C05-002003)

    • GT.M socket devices now allow up to the number of clients specified in the environment variable gtm_max_sockets. The default limit is 64, and there is an absolute maximum which at this point in human history exceeds your wildest dreams. $VIEW("MAX_SOCKETS") returns the current value. (C9C10-002149)

    • [V5.2-000A] ZWRITE with a range (n:m) no longer no longer occasionally fails with a segmentation fault (SIG-11). [AIX; Solaris] (C9D01-002239)

    • The maximum length for the argument to the ZSYSTEM command has increased to 4K bytes.[UNIX] (C9E09-002637)

    • [V5.2-000A] Messages and Recovery Procedures Manual is now current up to V5.2-000A. See http://www.fidelityinfoservices.com/user_documentation/V52AMsgRecProc/index.htm. (C9F07-002745)

    • OPEN of TCP device with an invalid address specification now gives an appropriate error rather than terminating the process. (C9G12-002808)

    • [V5.2-000A] Pattern match with multiple unbounded patterns where a lower bound after the first unbounded pattern is 7 (9 for V5.2-000) or more now gives the correct result. For example, in GT.M V5.2 (1.1?.n1"."9.n), and, in prior versions, (1.1?.n1"."7.n) incorrectly returned 1. (C9G12-002813)

    • [V5.2-000A] GT.M now reports complete error messages where in V5.2-000 utf-8 mode they were terminated at the first non-ASCII character. [HP-UX] (C9G12-002815)

    • [V5.2-000A] GT.M no longer inappropriately issues a GTM-E-GTMSECSHRSOCKET when it finds a socket conflict (usually because of an abandoned socket) for use in activating GTMSECSHR actions.[UNIX] (C9H03-002828)

    • [V5.2-000A] GT.M introduces a new deviceparameter called MOREREADTIME that applies to OPEN and USE commands for a SOCKET device. Except when a READ has a zero (0) timeout, MOREREADTIME specifies the time (in milliseconds) that a READ waits for input.

      • By default, MOREREADTIME is 10.
      • When MOREREADTIME is set to -1, it takes the default value of 10.
      • The maximum value of MORETREADTIME is 999 (basically 1 second). GTM triggers the MRTMAXEXCEEDED error if MOREREADTIME exceeds the maximum value.
      • Previous versions of GT.M used a fixed value of 200ms.
      [Note]
      This change may affect the operational behavior of TCP/IP aspects of your application. If the impact is adverse, specify a value of 200 milliseconds to restore the previous behavior.

      @@ -241,13 +241,13 @@ To implement approach 1 in MUMPS, specify a delimiter in an OPEN or USE command

      To implement approach 2, use a pair of fixed-length READs (READ #). Specifying a large value of MOREREADTIME is appropriate for Approach 1 and 2, but it tends to make Approach 3 work sub-optimally (except when it is implemented with zero timeout READ).

      Specify a short value of MOREREADTIME for Approach 3. However, when used together with Approach 1 and 2, it uses CPU less efficiently than otherwise.

      -
      [Warning]
      Never set MOREREADTIME to 0 as it may cause a CPU to "spin". (C9H03-002835)
      -

    • [V5.2-000B] +

      [Warning]
      Never set MOREREADTIME to 0 as it may cause a CPU to "spin". (C9H03-002835)
      +

    • [V5.2-000B] READ * in M-mode on Sequential Disk file and Socket device of a character with encoding between 128 to 255 inclusive now returns the correct code value. This fixes a problem introduced in V5.2-000 that resulted in READ * on those devices returning an incorrect (negative) value. (C9H04-002843)

    Return to top

    Utilities-MUPIP

    • The CHECKHEALTH, SHOWBACKLOG and SHUTDOWN qualifiers in a MUPIP REPLIC -SOURCE command now honor the value (if any) specified in the environment variable gtm_repl_instsecondary. [UNIX] (S9G07-002618)

    • MUPIP RUNDOWN now correctly uses an INFO message severity at its termination which prevents its hanging. This problem was introduced in V5.1-000 and is now fixed. [OpenVMS] (S9G07-002619)

    • MUPIP ENDIANCVT no longer terminates with an error while trying to convert a V5.0 format database. (S9G08-002621)

    • [V5.2-000A] MUPIP INTRPT command no longer causes the loss of data in the input buffer on a terminal READ or direct mode.

      If an interrupt (sent by the MUPIP INTRPT command) triggers code that does not resume from where the process was interrupted while a terminal READ is in progress, GT.M discards all input that the terminal READ received up to the time of that interrupt. ZSHOW "D" in a $ZINTERRUPT routine now includes a "ZINTERRUPT" designation for a terminal device if MUPIP INTRPT interrupted input on a terminal READ. Fidelity recommends that applications declare $ZINTERRPT routine specific $ETRAP/$ZTRAP error handlers in the interrupt processing code. -

      MUPIP INTRPT no longer causes the loss of previously received input on a terminal READ or direct mode. While GT.M processes an interrupt through the MUPIP INTRPT command, the only operation that GT.M permits on the current device ($IO) is the USE command with no deviceparameters. All other actions (CLOSE, OPEN, READ, WRITE) to that device trigger the ZINTRECURSEIO error. GT.M also triggers the ZINTDIRECT error for all attempts to BREAK into direct mode while that interrupt is processed. This allows the interrupt processing code to use another device and then restore the original device in an undisturbed state so that the interrupted application can resume as if uninterrupted (at least as far as the device behavior is concerned).[UNIX] (S9G12-002636)

    • [V5.2-000A] Both socket /WAIT (server side) and socket READ now respond to MUPIP INTRPT. A socket device performing a client connect operation does not currently respond to an INTRPT until the connection is complete. (C9G04-002779, S9G03-002602)

      [Important]
      Note that the TCP device is not changed and still does not respond to INTRPT. FIS recommends replacing the deprecated TCP device usage with the standard SOCKET device.

    • MUPIP ENDIANCVT now ensures that buffers in shared memory are flushed to disk and completes close of its output file before printing success. (C9G06-002799)

    • If the environment variable gtm_quiet_halt is set to 1, then if the process is stopped via MUPIP STOP or by a SIGTERM signal (as is sent by some web servers), the FORCEDHALT message will be suppressed as it is assumed that this is the "normal" way this type of process will terminate. Full robust process termination, database flush, cleanup etc will be performed as is normally done. [UNIX] (C9G12-002812)

    • [V5.2-000A] A Journal file's name can now include characters in Unicode™.[HP-UX] (C9G12-002814)

    • In rare cases where processes accessing a GT.M database were terminated abnormally, MUPIP RUNDOWN on that database could terminate prematurely with a SIG-11. This is now fixed.[UNIX] (C9F09-002755)

    • [V5.2-000A] Users now have the option to install GT.M with or without Unicode-related functionality. GT.M now installs components related to the M-mode only on a computer which does not have ICU. GT.M continues to require ICU for functionality related to UTF-8 mode. (C9H02-002821)

    • [V5.2-000A] GT.M now produces correct process initiation (“pini”) records in a journal file created during a recovery from an event that happens to interrupt a database file extension, where in prior versions this rare occurrence could result in an incorrect record. Such an incorrect record would not generally be noticed in M mode, but could cause a BADCHAR error in UTF-8 mode. (C9H03-002832)

    • [V5.2-000A] In a backward rollback/recovery GT.M now avoids counting blocks requiring a V4 to V5 upgrade more than once when the action is interrupted and reissued more than once. In prior versions, a MUPIP INTEG of the recovered database could report a benign DBBTUWRNG integrity error, which it then automatically fixed. [UNIX] (C9H03-002836)

    +

    MUPIP INTRPT no longer causes the loss of previously received input on a terminal READ or direct mode. While GT.M processes an interrupt through the MUPIP INTRPT command, the only operation that GT.M permits on the current device ($IO) is the USE command with no deviceparameters. All other actions (CLOSE, OPEN, READ, WRITE) to that device trigger the ZINTRECURSEIO error. GT.M also triggers the ZINTDIRECT error for all attempts to BREAK into direct mode while that interrupt is processed. This allows the interrupt processing code to use another device and then restore the original device in an undisturbed state so that the interrupted application can resume as if uninterrupted (at least as far as the device behavior is concerned).[UNIX] (S9G12-002636)

  • [V5.2-000A] Both socket /WAIT (server side) and socket READ now respond to MUPIP INTRPT. A socket device performing a client connect operation does not currently respond to an INTRPT until the connection is complete. (C9G04-002779, S9G03-002602)

    [Important]
    Note that the TCP device is not changed and still does not respond to INTRPT. FIS recommends replacing the deprecated TCP device usage with the standard SOCKET device.

  • MUPIP ENDIANCVT now ensures that buffers in shared memory are flushed to disk and completes close of its output file before printing success. (C9G06-002799)

  • If the environment variable gtm_quiet_halt is set to 1, then if the process is stopped via MUPIP STOP or by a SIGTERM signal (as is sent by some web servers), the FORCEDHALT message will be suppressed as it is assumed that this is the "normal" way this type of process will terminate. Full robust process termination, database flush, cleanup etc will be performed as is normally done. [UNIX] (C9G12-002812)

  • [V5.2-000A] A Journal file's name can now include characters in Unicode™.[HP-UX] (C9G12-002814)

  • In rare cases where processes accessing a GT.M database were terminated abnormally, MUPIP RUNDOWN on that database could terminate prematurely with a SIG-11. This is now fixed.[UNIX] (C9F09-002755)

  • [V5.2-000A] Users now have the option to install GT.M with or without Unicode-related functionality. GT.M now installs components related to the M-mode only on a computer which does not have ICU. GT.M continues to require ICU for functionality related to UTF-8 mode. (C9H02-002821)

  • [V5.2-000A] GT.M now produces correct process initiation (“pini”) records in a journal file created during a recovery from an event that happens to interrupt a database file extension, where in prior versions this rare occurrence could result in an incorrect record. Such an incorrect record would not generally be noticed in M mode, but could cause a BADCHAR error in UTF-8 mode. (C9H03-002832)

  • [V5.2-000A] In a backward rollback/recovery GT.M now avoids counting blocks requiring a V4 to V5 upgrade more than once when the action is interrupted and reissued more than once. In prior versions, a MUPIP INTEG of the recovered database could report a benign DBBTUWRNG integrity error, which it then automatically fixed. [UNIX] (C9H03-002836)

    • Return to top

    Utilities-Other Than MUPIP

    • The INSTALL script no longer terminates prematurely on some HP-UX systems.[HP-UX] (S9G11-002627)

    • DSE ALL -DUMP [-ALL] now dumps the fileheader for all regions in the global directory. The -ALL qualifier selects the comprehensive format. The default is the briefer format. The -DUMP qualifier can only be intermixed with the -ALL qualifier. (C9G04-002784)

    • [V5.2-000A] DBCERTIFY CERTIFY now correctly handles all conditions that lead to a split in the root level of a global variable tree. Previously these (fortunately rare) conditions triggered occasional spurious DBCMODBLK2BIG errors and the only workaround was to revert to a V4 format database and then repeat the scan/upgrade process. DBCERTIFY now always operates in M mode, while in V5.2-000 it could inappropriately attempt to operate in UTF-8 mode.

      Also, the V5CBSU utility no longer triggers an occasional spurious INVFCN errors when it encounters a character with encoding in the range of 128-255. This problem was specific to V5.2-000 version only. [UNIX] (C9G04-002790)

    Return to top

    Error Messages

    Return to top

    BADCASECODE

    diff --git a/articles/GTM_V5.3-000_Release_Notes.html b/articles/GTM_V5.3-000_Release_Notes.html index 478ffbf..f2ffc93 100644 --- a/articles/GTM_V5.3-000_Release_Notes.html +++ b/articles/GTM_V5.3-000_Release_Notes.html @@ -78,7 +78,7 @@

    11.11

    GT.M supports UTF-8 mode and M mode on this platform.

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent Fidelity from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. Fidelity understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent Fidelity from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. Fidelity understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) 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 (as root) can be used to determine if this patch has been applied. Note that recent "BATCH" and "GOLDEN" patches may contain this patch therefore a user's system may already have this patch applied but may not list it separately. Contact an HP service representative for more information.

    @@ -100,7 +100,7 @@

    5.2/5.3

    		 -
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent Fidelity from testing 4-byte UTF-8 characters more comprehensively on this platform than on others.
    +
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent Fidelity from testing 4-byte UTF-8 characters more comprehensively on this platform than on others.

    Sun SPARC Solaris

    @@ -156,7 +156,7 @@

    4-byte (32 bit)

    gtm_uint_t has 32 bit length on all platforms

    -
    [Caution]
    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 and potentially dangerous and hard to diagnose ways. In testing, GTMASSERT and SEGV (signal-11) errors were most common caused by storage chain (malloc) corruption failures.

    Internationalization (Collation)

    +
    [Caution]
    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 and potentially dangerous and hard to diagnose ways. In testing, GTMASSERT and SEGV (signal-11) errors were most common caused by storage chain (malloc) corruption failures.

    Internationalization (Collation)

    Parameter type

    32-Bit

    @@ -172,7 +172,7 @@

    8-byte (64-bit)

    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.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -188,7 +188,7 @@

    8-byte (64-bit)

    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.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled in the 64-bit environment, the source is identical to the 32-bit editions.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On the Linux platform, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    • Relink all object files after recompiling all M and C source files.

    Return to top

    Global Directory Upgrade

    Users who upgrade from GT.M V5.0-000 or later do not require a global directory upgrade.

    Users on the Integrity IA64 platforms must create new global directories as the format on 64 bit editions differs from 32 bit editions.

    Users who upgrade from a GT.M version prior to V5.0-000 require a global directory upgrade because the V5 global directory format is different from a V4 global directory format. When a user opens a V4 global directory with the V5 GDE utility program, even if they make no changes, an EXIT command automatically replaces the V4 format global directory file with a V5 format global directory file.

    [Note]
    Fidelity strongly recommends users make a copy of any global directory before upgrading it. There is no way to downgrade a global directory from V5 format to V4 format.

    If a user inadvertently opens V4 global directory with a V5 GDE with no intention of upgrading it, then execute the QUIT command rather than the EXIT command.

    If a user inadvertently upgrades a global directory, then perform the following steps:

    1. Open the global directory with V5 GDE.
    2. Execute the SHOW ALL command.
    3. Then, edit the output into a command file or manually enter the commands corresponding to the output into a V4 GDE invocation.

    Return to top

    Database Upgrade

    Users who upgrade from a GT.M version prior to V5.0-000 need to perform a database upgrade. See Database Migration Technical Bulletin (Database Migration Technical Bulletin) for more information on the database upgrade procedure. No database upgrade is necessary for users who upgrade from GT.M V5.0-000 or later.

    [Note]
    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Return to top

    Installation Instructions

    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. Users who overwrite an existing GT.M installation with a new version must shut down all processes using the old version.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to bring down any open database files.

    3. In UNIX editions, make sure gtmsecshr is not running. If found running, perform kill <pid of gtmsecshr>.

      [Caution]
      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).

    4. In UNIX editions, the GT.M configure script asks the following question:

      Enter the RC node ID of the GT.CM server, if desired (42).

    5. Respond by pressing ENTER.

    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:

    • +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled in the 64-bit environment, the source is identical to the 32-bit editions.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On the Linux platform, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    • Relink all object files after recompiling all M and C source files.

    Return to top

    Global Directory Upgrade

    Users who upgrade from GT.M V5.0-000 or later do not require a global directory upgrade.

    Users on the Integrity IA64 platforms must create new global directories as the format on 64 bit editions differs from 32 bit editions.

    Users who upgrade from a GT.M version prior to V5.0-000 require a global directory upgrade because the V5 global directory format is different from a V4 global directory format. When a user opens a V4 global directory with the V5 GDE utility program, even if they make no changes, an EXIT command automatically replaces the V4 format global directory file with a V5 format global directory file.

    [Note]
    Fidelity strongly recommends users make a copy of any global directory before upgrading it. There is no way to downgrade a global directory from V5 format to V4 format.

    If a user inadvertently opens V4 global directory with a V5 GDE with no intention of upgrading it, then execute the QUIT command rather than the EXIT command.

    If a user inadvertently upgrades a global directory, then perform the following steps:

    1. Open the global directory with V5 GDE.
    2. Execute the SHOW ALL command.
    3. Then, edit the output into a command file or manually enter the commands corresponding to the output into a V4 GDE invocation.

    Return to top

    Database Upgrade

    Users who upgrade from a GT.M version prior to V5.0-000 need to perform a database upgrade. See Database Migration Technical Bulletin (Database Migration Technical Bulletin) for more information on the database upgrade procedure. No database upgrade is necessary for users who upgrade from GT.M V5.0-000 or later.

    [Note]
    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Return to top

    Installation Instructions

    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. Users who overwrite an existing GT.M installation with a new version must shut down all processes using the old version.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to bring down any open database files.

    3. In UNIX editions, make sure gtmsecshr is not running. If found running, perform kill <pid of gtmsecshr>.

      [Caution]
      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).

    4. In UNIX editions, the GT.M configure script asks the following question:

      Enter the RC node ID of the GT.CM server, if desired (42).

    5. Respond by pressing ENTER.

    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 in one of the following modes:

    • smit aio (for gui mode) or @@ -199,7 +199,7 @@

      Users who 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 must execute the same command after installing the new version of GT.M before using it. Users who define the GT.M commands to the system other than during the installation of GT.M need to 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 to match the proper GTMCOMMANDS.CLD with the version of GT.M being used.

    Post Installation Instructions

    When you complete the installation of V5.3-000, run the MUPIP REORG -UPDATE command.

    If you have upgraded from a pre-V5 version to V5.3-000, then the MUPIP REORG -UPDATE command upgrades all the blocks.

    If you have upgraded from another V5 version to V5.3-000, the MUPIP REORG -UPDATE command cleans those recycled database blocks that escaped prior upgrade activities. This command also adjusts the file header to stop log message like the following:

     GTM[iiii]: %GTM-W-DBVERPERFWARN2, Peformance warning: Database /home/voet/EHR/g/mumps.dat is not fully upgraded. 
 Run MUPIP REORG UPGRADE for best overall performance -- generated from 0xaaaaaaaa
-

    where iiii is a process id and aaaaaaaa is a hexadecimal address that depends on your platform.

    Managing M mode and UTF-8 mode

    On a system that does not have ICU installed, GT.M assumes M mode operation and installs M mode components only.

    On a system that has ICU installed, GT.M installs both M mode and UTF-8 mode components and an additional utf8 subdirectory. The technique that GT.M uses to separate M mode and UTF-8 mode object files is as follows:

    From the same source file, the GT.M compiler generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. 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. GT.M processes trigger an error if the object file was generated with a different setting of gtm_chset/$ZCHset than the current value.

    Always generate an M object module with a value of gtm_chset that matches the value that a process executing that module will have. As the GT.M product contains M utility programs, their object files must conform to this rule. In order for the users to be able to use both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 "flavors" of object modules exist and can be found in known locations. The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use. Users should consider a similar pattern for structuring application object code repositories.

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

    • Most GT.M (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified by the environment variable gtm_dist.

    • Object files for programs written in M (GDE, utilities) have two versions-- one compiled for support of Unicode™ in the utf8 subdirectory, and one compiled without support of Unicode™ in the parent directory. Installing GT.M (V5.2-000 and above) generates both the versions of object files. Note that GT.M generates the object files for utf8 subdirectory only if ICU 3.6 is installed on the system.

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

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

      • If gtm_chset is "m", "M" or undefined, there is no change to the environment from the previous versions.

      • If gtm_chset is "UTF-8",

        • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/local/gtm_V5.2-001, then $gtm_dist is set to /usr/local/gtm_V5.2-001/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.

    Setting the environment variable TERM

    Users must set the environment variable TERM to 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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    V5.3-000 Change History

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

    S9H05-002658
    S9H08-002667
    S9H08-002668
    C9B11-001813
    C9B11-001813A
    C9C11-002165
    C9D07-002357
    C9E05-002604
    C9F09-002753
    C9F10-002762
    C9H05-002863
    C9H07-002873
    C9H07-002876
    C9H07-002883
    C9H08-002888
    C9H08-002890
    C9H09-002901
    C9H09-002905

    Return to top

    M-Database Access

    +

    where iiii is a process id and aaaaaaaa is a hexadecimal address that depends on your platform.

    Managing M mode and UTF-8 mode

    On a system that does not have ICU installed, GT.M assumes M mode operation and installs M mode components only.

    On a system that has ICU installed, GT.M installs both M mode and UTF-8 mode components and an additional utf8 subdirectory. The technique that GT.M uses to separate M mode and UTF-8 mode object files is as follows:

    From the same source file, the GT.M compiler generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. 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. GT.M processes trigger an error if the object file was generated with a different setting of gtm_chset/$ZCHset than the current value.

    Always generate an M object module with a value of gtm_chset that matches the value that a process executing that module will have. As the GT.M product contains M utility programs, their object files must conform to this rule. In order for the users to be able to use both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 "flavors" of object modules exist and can be found in known locations. The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use. Users should consider a similar pattern for structuring application object code repositories.

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

    • Most GT.M (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified by the environment variable gtm_dist.

    • Object files for programs written in M (GDE, utilities) have two versions-- one compiled for support of Unicode™ in the utf8 subdirectory, and one compiled without support of Unicode™ in the parent directory. Installing GT.M (V5.2-000 and above) generates both the versions of object files. Note that GT.M generates the object files for utf8 subdirectory only if ICU 3.6 is installed on the system.

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

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

      • If gtm_chset is "m", "M" or undefined, there is no change to the environment from the previous versions.

      • If gtm_chset is "UTF-8",

        • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/local/gtm_V5.2-001, then $gtm_dist is set to /usr/local/gtm_V5.2-001/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.

    Setting the environment variable TERM

    Users must set the environment variable TERM to 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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    V5.3-000 Change History

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

    S9H05-002658
    S9H08-002667
    S9H08-002668
    C9B11-001813
    C9B11-001813A
    C9C11-002165
    C9D07-002357
    C9E05-002604
    C9F09-002753
    C9F10-002762
    C9H05-002863
    C9H07-002873
    C9H07-002876
    C9H07-002883
    C9H08-002888
    C9H08-002890
    C9H09-002901
    C9H09-002905

    Return to top

    M-Database Access

    • GT.M now handles name-level $ORDER(gvn,-1) and $ZPREVIOUS(gvn) operations which move between database regions appropriately. In prior versions, if the region holding global name specified in the argument had a smaller maximum key size than the region holding the result, it could cause process memory corruption and possible shared memory corruption, which could, in turn, cause database corruption. (S9H05-002658)

    • Before-image journaling now writes a correct checksum on journal records in a few cases where it formerly did not, which would cause MUPIP RECOVER/ROLLBACK to issue a "Checksum validation failed" error. This issue was reported as fixed in GT.M V5.0-000D as part of C9F10-002762 but this item addresses a few rare cases that remained. (C9F10-002762)

    • GT.M now timestamps journal records such that the times never decrease in the record sequence. Prior versions of GT.M could, in rare cases, write journal records with out-of-order timestamps when recording transactions that used ZTSTART/ZTCOMMIT semantics, which could cause problems with backward journal recovery. Note that FIS strongly recommends TSTART/TCOMMIT transaction processing over ZTSTART/ZTCOMMIT. (C9E05-002604)

    • diff --git a/articles/GTM_V5.3-001A_Release_Notes.html b/articles/GTM_V5.3-001A_Release_Notes.html index 0579d50..823037d 100644 --- a/articles/GTM_V5.3-001A_Release_Notes.html +++ b/articles/GTM_V5.3-001A_Release_Notes.html @@ -47,7 +47,7 @@

    -

    Table of Contents

    Typographical Conventions
    Bulletin Overview
    Platforms
    Migrating to 64-bit platforms
    Call-ins and External Calls
    Internationalization (Collation)
    Environment Translation
    Recompile
    Rebuild Shared Libraries or Images
    Global Directory Upgrade
    Additional Installation Instructions
    UNIX
    OpenVMS
    Database Upgrade Procedure
    Pre V5.0-000 to V5.3*
    V5.0*/V5.1*/V5.2* to V5.3*
    Managing M mode and UTF-8 mode
    Setting the environment variable TERM
    Change History
    V5.3-001A
    V5.3-001
    M-Database Access
    M-Other Than Database Access
    Utilities- MUPIP
    Utilities-Other Than MUPIP
    Error Messages
    GTMSECSHRTMPPATH
    OPCOMMISSED [V5.3-001A]

    Return to top

    Typographical Conventions

    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 "/".

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

    Return to top

    Bulletin Overview

    +

    Table of Contents

    Typographical Conventions
    Bulletin Overview
    Platforms
    Migrating to 64-bit platforms
    Call-ins and External Calls
    Internationalization (Collation)
    Environment Translation
    Recompile
    Rebuild Shared Libraries or Images
    Global Directory Upgrade
    Additional Installation Instructions
    UNIX
    OpenVMS
    Database Upgrade Procedure
    Pre V5.0-000 to V5.3*
    V5.0*/V5.1*/V5.2* to V5.3*
    Managing M mode and UTF-8 mode
    Setting the environment variable TERM
    Change History
    V5.3-001A
    V5.3-001
    M-Database Access
    M-Other Than Database Access
    Utilities- MUPIP
    Utilities-Other Than MUPIP
    Error Messages
    GTMSECSHRTMPPATH
    OPCOMMISSED [V5.3-001A]

    Return to top

    Typographical Conventions

    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 "/".

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

    Return to top

    Bulletin Overview

    V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to defects, including an issue with NOUNDEF handling, an issue with TP transactions that include multiple global directories, as well as some other issues.

    GT.M V5.3-001 introduced support for 64-bit GT.M processes to x86_64 GNU/Linux and IBM pSeries AIX.

    For a brief description of the fixes and enhancements in this release, see section Change History.

    [Note]
    Placing databases on raw partitions is no longer supported, and references thereto will be removed in the next update to the user documentation. Although the GT.M team is fastidious about maintaining upward compatibility, in this case, we are aware of no customer who is using GT.M on a raw partition. If you are a GT.M customer using raw partitions for GT.M databases, please contact GT.M Support (gtmsupport@fnis.com) as soon as possible.

    Return to top

    Platforms

    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.

    @@ -67,7 +67,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    11V2(11.23)

    Database performance may be unsatisfactory unless you apply patch PHKL_37279

    -
    [Warning]
    V5.3-0001A does not properly support the SOCKET devices when used with 11V3 (11.31); this will be addressed in the next release. We are aware of no other issues with 11.31, but consider it not formally Supported for V5.3-001A.
    +
    [Warning]
    V5.3-0001A does not properly support the SOCKET devices when used with 11V3 (11.31); this will be addressed in the next release. We are aware of no other issues with 11.31, but consider it not formally Supported for V5.3-001A.

    IA64 GNU/Linux - Red Hat Enterprise Linux

    @@ -84,7 +84,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    11.11

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

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) 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 (as root) can be used to determine if this patch has been applied. Note that recent "BATCH" and "GOLDEN" patches may contain this patch therefore your system may already have this patch applied but may not list it separately. Contact an HP service representative for more information.

    @@ -112,7 +112,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    Although AIX 5.2 and 5.3 are the officially supported releases, we are not aware of any reason why GT.M V5.3-001A will not run on AIX 6.x.

    -
    [Tip]
    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.
    +
    [Tip]
    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.

    Sun SPARC Solaris

    @@ -178,7 +178,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    4-byte

    gtm_uint_t has 32 bit length on all platforms

    -
    [Caution]
    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)

    +
    [Caution]
    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

    @@ -194,7 +194,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    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.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -210,9 +210,9 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    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.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    Return to top

    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 top

    Global Directory Upgrade

    Global directory formats differ for 32- and 64-bit GT.M platforms. This means that:

    • The global directory format differs between GT.M on x86 GNU/Linux and that of x86_64 GNU/Linux.
    • On AIX, the global directory format differs between GT.M on V5.3-001 and prior versions.

    +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    Return to top

    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 top

    Global Directory Upgrade

    Global directory formats differ for 32- and 64-bit GT.M platforms. This means that:

    • The global directory format differs between GT.M on x86 GNU/Linux and that of x86_64 GNU/Linux.
    • On AIX, the global directory format differs between GT.M on V5.3-001 and prior versions.

    Furthermore, on Itanium platforms, there is a difference in global directory formats between V5.3-000 and V5.3-001. -

    Except for the above cases, you do not require a global directory upgrade when moving up from GT.M V5.0-000 or later.

    Moving up from a GT.M version prior to V5.0-000, from a 32-bit global directory to a 64-bit global directory, or on Itanium platforms migrating from V5.3-000 to V5.3-001 requires a global directory upgrade. Opening a global directory with the GDE utility program from the latest GT.M version (or the 64-bit x86_64 format for that platform), followed by an EXIT command automatically, even with no other intervening commands, upgrades the global directory.

    [Note]
    FIS strongly recommends you make a copy of any global directory before upgrading it. There is no way to downgrade a global directory to an earlier format.

    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 the current version.
    2. Execute the SHOW ALL command.
    3. Create a command file, or manually enter the commands corresponding to the output, into GDE from the prior GT.M version.

    Return to top

    Additional Installation Instructions

    For installing 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. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-001A in /opt/lsb-gtm/V5.3-001A on Linux systems.

    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 >.

      [Caution]
      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:

    • +

      Except for the above cases, you do not require a global directory upgrade when moving up from GT.M V5.0-000 or later.

      Moving up from a GT.M version prior to V5.0-000, from a 32-bit global directory to a 64-bit global directory, or on Itanium platforms migrating from V5.3-000 to V5.3-001 requires a global directory upgrade. Opening a global directory with the GDE utility program from the latest GT.M version (or the 64-bit x86_64 format for that platform), followed by an EXIT command automatically, even with no other intervening commands, upgrades the global directory.

      [Note]
      FIS strongly recommends you make a copy of any global directory before upgrading it. There is no way to downgrade a global directory to an earlier format.

      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 the current version.
      2. Execute the SHOW ALL command.
      3. Create a command file, or manually enter the commands corresponding to the output, into GDE from the prior GT.M version.

    Return to top

    Additional Installation Instructions

    For installing 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. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-001A in /opt/lsb-gtm/V5.3-001A on Linux systems.

    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 >.

      [Caution]
      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 in one of the following modes:

    • smit aio (for gui mode) or @@ -236,9 +236,9 @@ gmake gmake check gmake install

    • 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.

    [Note]
    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.

    Return to top

    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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    Change History

    Return to top

    V5.3-001A

    Fixes and enhancements specific to V5.3-001A are:

    S9I03-002674
    S9I03-002675
    S9I03-002676
    C9C11-002181
    C9D01-002232
    C9D01-002234
    C9E04-002596
    C9E08-002617
    C9I02-002956
    C9I02-002959
    C9I02-002960
    C9I02-002963
    C9I03-002964
    C9I03-002967
    C9I03-002969
    C9I03-002971

    These fixes are marked with [V5.3-001A] in the subsequent sections.

    Fixes and enhancements specific to V5.3-001 are:

    S9E08-002478
    S9G12-002633
    S9H11-002670
    C9B03-001664
    C9D10-002409
    C9G04-002788
    C9H07-002880
    C9H09-002899
    C9H09-002900
    C9H10-002916
    C9H10-002918
    C9H10-002923
    C9H11-002926
    C9H11-002927
    C9H11-002932
    C9H12-002934
    C9I01-002938
    C9I01-002939

    Return to top

    M-Database Access

    +

    • 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.

    Return to top

    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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    Change History

    Return to top

    V5.3-001A

    Fixes and enhancements specific to V5.3-001A are:

    S9I03-002674
    S9I03-002675
    S9I03-002676
    C9C11-002181
    C9D01-002232
    C9D01-002234
    C9E04-002596
    C9E08-002617
    C9I02-002956
    C9I02-002959
    C9I02-002960
    C9I02-002963
    C9I03-002964
    C9I03-002967
    C9I03-002969
    C9I03-002971

    These fixes are marked with [V5.3-001A] in the subsequent sections.

    Fixes and enhancements specific to V5.3-001 are:

    S9E08-002478
    S9G12-002633
    S9H11-002670
    C9B03-001664
    C9D10-002409
    C9G04-002788
    C9H07-002880
    C9H09-002899
    C9H09-002900
    C9H10-002916
    C9H10-002918
    C9H10-002923
    C9H11-002926
    C9H11-002927
    C9H11-002932
    C9H12-002934
    C9I01-002938
    C9I01-002939

    Return to top

    M-Database Access

    • The Linux version of GT.M can now utilize O_DIRECT support for journal files. The O_DIRECT option is made available by using the sync_io option to the MUPIP SET -JOURNAL command just as for the other platforms that support direct I/O. [Linux] (C9D10-002409) -

    • [V5.3-001A] GT.M now appropriately handles TP transactions that include multiple global directories (due to SET $ZGBLdir or extended references) having multiple regions that map to the same database file. Previous versions could, in rare cases, terminate the GT.M process abnormally with TPFAIL or SIG-11 errors (ACCVIO in VMS) and damage the database if TP transactions accessed global variables in such a database files via different global directories.

      [Note]
      If you use the VIEW "NOISOLATION" command to turn NOISOLATION characteristics ON for a global name in one global directory and turn it OFF for the same name in a different global directory and if the two global directories map the global name to the same database file, then GT.M leaves NOISOLATION OFF if any path specifies OFF, irrespective of the order of the specifying VIEW command. (C9E04-002596)

    • After changing $ZGBLDIR, $VIEW() now properly reflects the current value of $ZGBLDIR even with no intervening global variable access. Previously this sequence could give an incorrect answer, or a memory access violation with the workaround being to perform an intervening global variable access. (C9H09-002900)

    • The GT.M database critical section lock wakeup mechanism has been enhanced to use memory semaphores. Previous versions used a socket-based scheme for wakeup. In some cases this led to processes being blocked trying to wake other processes up. This is no longer an issue in the new scheme. Since memory semaphores were introduced in 2.6 kernels, running GT.M on 2.4 kernels now requires a kernel which has had memory semaphores back-ported from 2.6. Note that contemporary releases of major Linux distributions use 2.6 kernels. [Linux] (C9H10-002918).

    • GT.M now avoids restarting a TP transaction in some additional cases where the global variable it is planning on updating has NOISOLATION turned ON even though it has been concurrently updated thereby improving GT.M transaction throughput rates. (C9I01-002938)

    • TP transactions now do not sleep between TP restarts thereby improving GT.M transaction throughput rates. Previously they used to sleep for a short time between every restart potentially resulting in inefficient use of system resources. (C9I01-002939)

    • [V5.3-001A] Using TSTART with no prior global reference now works if you precede it with a SET $ZGBLDIR command and no intervening database references. In previous GT.M versions, such an unusual usage would terminate a GT.M process abnormally with SIG-11 (ACCVIO in VMS) errors. (C9I02-002963)

    • [V5.3-001A] +

    • [V5.3-001A] GT.M now appropriately handles TP transactions that include multiple global directories (due to SET $ZGBLdir or extended references) having multiple regions that map to the same database file. Previous versions could, in rare cases, terminate the GT.M process abnormally with TPFAIL or SIG-11 errors (ACCVIO in VMS) and damage the database if TP transactions accessed global variables in such a database files via different global directories.

      [Note]
      If you use the VIEW "NOISOLATION" command to turn NOISOLATION characteristics ON for a global name in one global directory and turn it OFF for the same name in a different global directory and if the two global directories map the global name to the same database file, then GT.M leaves NOISOLATION OFF if any path specifies OFF, irrespective of the order of the specifying VIEW command. (C9E04-002596)

    • After changing $ZGBLDIR, $VIEW() now properly reflects the current value of $ZGBLDIR even with no intervening global variable access. Previously this sequence could give an incorrect answer, or a memory access violation with the workaround being to perform an intervening global variable access. (C9H09-002900)

    • The GT.M database critical section lock wakeup mechanism has been enhanced to use memory semaphores. Previous versions used a socket-based scheme for wakeup. In some cases this led to processes being blocked trying to wake other processes up. This is no longer an issue in the new scheme. Since memory semaphores were introduced in 2.6 kernels, running GT.M on 2.4 kernels now requires a kernel which has had memory semaphores back-ported from 2.6. Note that contemporary releases of major Linux distributions use 2.6 kernels. [Linux] (C9H10-002918).

    • GT.M now avoids restarting a TP transaction in some additional cases where the global variable it is planning on updating has NOISOLATION turned ON even though it has been concurrently updated thereby improving GT.M transaction throughput rates. (C9I01-002938)

    • TP transactions now do not sleep between TP restarts thereby improving GT.M transaction throughput rates. Previously they used to sleep for a short time between every restart potentially resulting in inefficient use of system resources. (C9I01-002939)

    • [V5.3-001A] Using TSTART with no prior global reference now works if you precede it with a SET $ZGBLDIR command and no intervening database references. In previous GT.M versions, such an unusual usage would terminate a GT.M process abnormally with SIG-11 (ACCVIO in VMS) errors. (C9I02-002963)

    • [V5.3-001A] GT.M now closes journaling and continues with database updates even if:

      • it encounters errors (for example, insufficient disk space errors ) while writing to the journal file, and
      • it is holding the critical section lock on the database file. If GT.M does not hold the critical section lock on the database file, then it waits in a sleep loop until it successfully writes to the journal file.
      @@ -264,18 +264,18 @@ Jan 23 17:17:40 host1 GTM[18950]: %GTM-I-GTMSECSHRTMPPATH, gtmsecshr path is /se Jan 23 17:17:40 host1 GTM[18964]: %GTM-F-GTMSECSHRSTART, Server - 18964 : gtmsecshr failed to startup, %GTM-I-TEXT, server already running, %SYSTEM-E-ENO11, Resource temporarily unavailable -- generated from 0x0804D275. Jan 23 17:17:40 host1 GTM[18964]: %GTM-I-GTMSECSHRTMPPATH, gtmsecshr path is /secshrpath/two, %GTM-I-TEXT, (from $gtm_tmp) -- generated from 0x0804D2E4. -

    • [V5.3-001A] GT.M now handles name indirection and call-ins in an a wholesome way. In V5.3-001, an inconsistency in handling these operations in NOUNDEF mode could cause various misfortunes including out of memory conditions and segmentation faults (SIG-11/ACCVIO). (S9I03-002674)

    • [V5.3-001A] GT.M now suppresses STACKCRIT errors in the current frame at the time of the error. Previously, GT.M suppressed STACKCRIT errors in stack levels invoked because of an error, but this did not cover the GOTO implicit in $ETRAP processing or any explicit GOTO or ZGOTO in a $ZTRAP that placed control at the original stack level of the error. (S9I03-002676)

      GT.M now signals the STACKCRIT error when a process has 16K stack space left available. This gives processes more opportunity to recover and trim the stack using QUIT, ZGOTO, or HALT. Previous versions used to display the STACKCRIT message when there was 1K stack space left. [UNIX] (S9I03-002676)

    • GT.M introduces a new environment variable gtm_noundef. If it is defined, and evaluates to a non-zero integer, the string "TRUE", or the string "YES" (or any case independent leading substrings thereof), then GT.M, at process startup, treats undefined variables as having an implicit value of an empty string. Otherwise, GT.M triggers an error on an attempt to use the value of an undefined variable. Previously the only way to alter this behavior of undefined variables was to use the UNDEF or NOUNDEF arguments of the VIEW command.

      [Note]
      To establish the behavior of undefined variables on OpenVMS, set "GTM$UNDEF_INHIBIT == 1" in GTM$DEFAULTS.M64 to treat undefined variables as having a null value or set "GTM$UNDEF_INHIBIT == 0" to trigger an error on an attempt to use the value of an undefined variable.

      Running with VIEW "NOUNDEF" no longer has the disconcerting result of a test of a value implicitly creating (with a null value) previous undefined local unsubscripted variables. Now, while the variables still appear to have a null value in NOUNDEF mode, they remain undefined and will not show up in the output of ZWRITE, and functions such as $DATA() and $ORDER().

      When running in VIEW "UNDEF" mode, $STACK(X,Y) where the variable Y is undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a INVSTACODE error.

      When running in VIEW "UNDEF" mode, JOB @LABEL+OFFSET^@ROUTINE where any of the variables LABEL, OFFSET or ROUTINE are undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a JOBFAIL error. (C9B03-001664)

    • [V5.3-001A] GT.M now handles an error while $ZTRAP is active (a recursive error) in a similar fashion to an error while $ETRAP is active -- $ZTRAP now returns to the previous stack level and does not enter the direct mode. $ZTRAP creates an implicit additional frame, and therefore GT.M clears the current $ZTRAP to avoid indefinite recursion. GT.M invokes any $ETRAP or $ZTRAP handler that it encounters during unwinding the stack. If GT.M cannot locate any valid handler, it eventually terminates the process or, if invoked from direct mode, returns to direct mode. This behavior means that production environments should always start with a mumps -run. In prior versions, if GT.M could not locate a valid handler during $ZTRAP error processing, it would enter direct mode as a last resort. Although this behavior may be appropriate for some development environments, it did not match many production requirements.

      GT.M now handles an error in an EXCEPTION or ZBREAK action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M would enter direct mode in those circumstances.

      GT.M now handles a compilation error in the SET of a $ZSTEP action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M ignored such errors. Note -- Unlike ZBREAK actions, $ETRAP, $ZTRAP, and EXCEPTION strings, $ZSTEP is compiled when it's SET rather than when it's first used. This means that the prior $ZTEP action value (which defaults to "B" - BREAK) is not changed on a defective SET. We don't expect or recommend production code use ZSTEP commands. Nonetheless, if it should happen to, we recommend ensuring $ZSTEP is successfully assigned a value other than the default; for example, $ZSTEP="" causes a ZSTEP to have no effect (other than to slow execution if ZSTEP is used). (C9C11-002181)

    • [V5.3-001A] GT.M now reports the correct error location if it encounters errors during $ZTRAP error handling. In prior versions, in some cases, certain errors could cause GT.M to misreport the current location particularly in $ZSTATUS, but potentially in other location reports, such as $ZPOSITION. (C9D01-002232, S9I03-002676)

    • [V5.3-001A] GT.M no longer triggers a GTMASSERT error (causing a process termination) while trying to determine the error location under certain conditions. Previous versions occasionally issued the spurious GTMASSERT error. (C9D01-002234, C9E08-002617)

    • GT.M processes on IBM pSeries AIX are now 64-bit. See "Migrating to 64-bit platform" and "Additional Information on AIX" for more information on installing GT.M on IBM pSeries AIX. [AIX] (C9G04-002788)

    • GT.M processes on the x86_64 GNU/Linux platform are now 64-bit. GT.M for x86 Linux (32-bit) remains available as a separate build and continues to run on both x86 and x86_64 platforms. On x86_64 GNU/Linux, GT.M now has the ability to generate object modules that can be included in shared libraries using the standard system ld utility. See "Migrating to 64-bit platform" and "Additional Information on Linux" for more information on installing GT.M on x86_64 GNU/Linux. [Linux] (C9H07-002880)

    • The v5cbsu V4 to V5 upgrade utility component now operates with TRANSACTIONID="BATCH" which reduces its run-time by not waiting for journal hardening. It is safe to do this because the v5cbsu can be safely rerun or restarted should the original run stop before it is complete. (C9H09-002899)

    • If an application fails to detect and act on the loss of a SOCKET $PRINCIPAL device (using $DEVICE, $ZEOF, or EXCEPTION) and attempts additional READs or WRITEs, GT.M handles this condition by sending a NOPRINCIO message to the system log and terminating the process (as if performing a HALT). (C9H10-002916)

    • GT.M now prevents a module on the execution stack from being ZLINK'd in a pathological case. A pattern where an attempted ZLINK of a program on the stack (which would fail, as it should), followed by a ZLINK of a program with the same name when it was not on the stack (which would succeed), was followed by a ZLINK of the same module name when it was again on the stack would not fail with an error (whereas it should). Subsequent behavior could include memory access violations. (C9H11-002926)

    • The "execstack" command is no longer needed to permit GT.M processes to execute dynamically generated code. [Linux] (C9H11-002927)

    • GT.M is now able to explicitly ZLink object modules in shared libraries. In prior versions, doing an explicit ZLink on an object module in a shared library produced a ZLink error. The new behavior is now consistent between explicit and implicit ZLinks. If you have $ZROUTINES search lists that assume that explicit ZLINK would bypass your shared libraries, you should revise those in light of what you were trying to accomplish. (C9H11-002932)

    • [V5.3-001A] GT.M no longer generates unaligned access errors in the system log files. Previously, due to an incorrect size of a structure in 64-bit UNIX versions of GT.M, running the gtcm_gnp server could generate unaligned access messages. (C9I02-002959)

    • [V5.3-001A] An auto-ZLINKing process now holds control of a newly generated object file until it completes loading the fresh code from it. Previous versions used to close the newly created object file at the end of the compile and then reopen it to load the code - this left a small window where another process could delete that file and cause a somewhat mystifying file-not-found error. (C9I02-002960)

    • [V5.3-001A] GT.M now guards against signals interrupting time requests other than those for internal use. Previously limitations on reentrancy of UNIX services could occasionally cause time requests to hang if a signal resulted in another time request while one was already active. [UNIX] (C9I03-002967)

    • [V5.3-001A]GT.M now reports if it encounters errors or a full OPCOM mailbox while trying to send operator messages; it sends this report at the first non-failing attempt. It also retries sending an operator message for the mail box full condition. [OpenVMS] (C9I03-002969)

    • [V5.3-001A] GT.M now manages object files on some 64-bit platforms in a way that avoids a small memory leak that existed in prior versions. [Linux/IA64, Linux/x86_64, HPUX/IA64] (C9I03-002971)

    Return to top

    Utilities- MUPIP

    • [V5.3-001A] The source server now replicates data correctly whether it reads from journal files or the journal pool. In GT.M V5.3-001, if the source server needed to read from journal files and if the journal files had sync_io turned on and were using alignsize values greater than 64Kb, it read more data than its internal buffers could hold leading to memory corruption and mysterious abnormal termination. [UNIX] (S9I03-002675)

    • The GT.M utilities except GDE (DSE, LKE, MUPIP) now require arguments and values entered directly from the shell and containing single-quote (') or double-quotes (") to have the quotes "protected" by an escape mechanism. Each one must be preceded by a back-slash (\) or the entire string must be enclosed in a set of quotes (single or double) that do not also appear in the string. Previously GT.M attempted to implicitly escape quotes within some strings when it added quotes in preprocessing strings, but that prior approach led to inconsistent behavior in certain cases. The following are examples of appropriate usage:

      +

    • [V5.3-001A] GT.M now handles name indirection and call-ins in an a wholesome way. In V5.3-001, an inconsistency in handling these operations in NOUNDEF mode could cause various misfortunes including out of memory conditions and segmentation faults (SIG-11/ACCVIO). (S9I03-002674)

    • [V5.3-001A] GT.M now suppresses STACKCRIT errors in the current frame at the time of the error. Previously, GT.M suppressed STACKCRIT errors in stack levels invoked because of an error, but this did not cover the GOTO implicit in $ETRAP processing or any explicit GOTO or ZGOTO in a $ZTRAP that placed control at the original stack level of the error. (S9I03-002676)

      GT.M now signals the STACKCRIT error when a process has 16K stack space left available. This gives processes more opportunity to recover and trim the stack using QUIT, ZGOTO, or HALT. Previous versions used to display the STACKCRIT message when there was 1K stack space left. [UNIX] (S9I03-002676)

    • GT.M introduces a new environment variable gtm_noundef. If it is defined, and evaluates to a non-zero integer, the string "TRUE", or the string "YES" (or any case independent leading substrings thereof), then GT.M, at process startup, treats undefined variables as having an implicit value of an empty string. Otherwise, GT.M triggers an error on an attempt to use the value of an undefined variable. Previously the only way to alter this behavior of undefined variables was to use the UNDEF or NOUNDEF arguments of the VIEW command.

      [Note]
      To establish the behavior of undefined variables on OpenVMS, set "GTM$UNDEF_INHIBIT == 1" in GTM$DEFAULTS.M64 to treat undefined variables as having a null value or set "GTM$UNDEF_INHIBIT == 0" to trigger an error on an attempt to use the value of an undefined variable.

      Running with VIEW "NOUNDEF" no longer has the disconcerting result of a test of a value implicitly creating (with a null value) previous undefined local unsubscripted variables. Now, while the variables still appear to have a null value in NOUNDEF mode, they remain undefined and will not show up in the output of ZWRITE, and functions such as $DATA() and $ORDER().

      When running in VIEW "UNDEF" mode, $STACK(X,Y) where the variable Y is undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a INVSTACODE error.

      When running in VIEW "UNDEF" mode, JOB @LABEL+OFFSET^@ROUTINE where any of the variables LABEL, OFFSET or ROUTINE are undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a JOBFAIL error. (C9B03-001664)

    • [V5.3-001A] GT.M now handles an error while $ZTRAP is active (a recursive error) in a similar fashion to an error while $ETRAP is active -- $ZTRAP now returns to the previous stack level and does not enter the direct mode. $ZTRAP creates an implicit additional frame, and therefore GT.M clears the current $ZTRAP to avoid indefinite recursion. GT.M invokes any $ETRAP or $ZTRAP handler that it encounters during unwinding the stack. If GT.M cannot locate any valid handler, it eventually terminates the process or, if invoked from direct mode, returns to direct mode. This behavior means that production environments should always start with a mumps -run. In prior versions, if GT.M could not locate a valid handler during $ZTRAP error processing, it would enter direct mode as a last resort. Although this behavior may be appropriate for some development environments, it did not match many production requirements.

      GT.M now handles an error in an EXCEPTION or ZBREAK action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M would enter direct mode in those circumstances.

      GT.M now handles a compilation error in the SET of a $ZSTEP action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M ignored such errors. Note -- Unlike ZBREAK actions, $ETRAP, $ZTRAP, and EXCEPTION strings, $ZSTEP is compiled when it's SET rather than when it's first used. This means that the prior $ZTEP action value (which defaults to "B" - BREAK) is not changed on a defective SET. We don't expect or recommend production code use ZSTEP commands. Nonetheless, if it should happen to, we recommend ensuring $ZSTEP is successfully assigned a value other than the default; for example, $ZSTEP="" causes a ZSTEP to have no effect (other than to slow execution if ZSTEP is used). (C9C11-002181)

    • [V5.3-001A] GT.M now reports the correct error location if it encounters errors during $ZTRAP error handling. In prior versions, in some cases, certain errors could cause GT.M to misreport the current location particularly in $ZSTATUS, but potentially in other location reports, such as $ZPOSITION. (C9D01-002232, S9I03-002676)

    • [V5.3-001A] GT.M no longer triggers a GTMASSERT error (causing a process termination) while trying to determine the error location under certain conditions. Previous versions occasionally issued the spurious GTMASSERT error. (C9D01-002234, C9E08-002617)

    • GT.M processes on IBM pSeries AIX are now 64-bit. See "Migrating to 64-bit platform" and "Additional Information on AIX" for more information on installing GT.M on IBM pSeries AIX. [AIX] (C9G04-002788)

    • GT.M processes on the x86_64 GNU/Linux platform are now 64-bit. GT.M for x86 Linux (32-bit) remains available as a separate build and continues to run on both x86 and x86_64 platforms. On x86_64 GNU/Linux, GT.M now has the ability to generate object modules that can be included in shared libraries using the standard system ld utility. See "Migrating to 64-bit platform" and "Additional Information on Linux" for more information on installing GT.M on x86_64 GNU/Linux. [Linux] (C9H07-002880)

    • The v5cbsu V4 to V5 upgrade utility component now operates with TRANSACTIONID="BATCH" which reduces its run-time by not waiting for journal hardening. It is safe to do this because the v5cbsu can be safely rerun or restarted should the original run stop before it is complete. (C9H09-002899)

    • If an application fails to detect and act on the loss of a SOCKET $PRINCIPAL device (using $DEVICE, $ZEOF, or EXCEPTION) and attempts additional READs or WRITEs, GT.M handles this condition by sending a NOPRINCIO message to the system log and terminating the process (as if performing a HALT). (C9H10-002916)

    • GT.M now prevents a module on the execution stack from being ZLINK'd in a pathological case. A pattern where an attempted ZLINK of a program on the stack (which would fail, as it should), followed by a ZLINK of a program with the same name when it was not on the stack (which would succeed), was followed by a ZLINK of the same module name when it was again on the stack would not fail with an error (whereas it should). Subsequent behavior could include memory access violations. (C9H11-002926)

    • The "execstack" command is no longer needed to permit GT.M processes to execute dynamically generated code. [Linux] (C9H11-002927)

    • GT.M is now able to explicitly ZLink object modules in shared libraries. In prior versions, doing an explicit ZLink on an object module in a shared library produced a ZLink error. The new behavior is now consistent between explicit and implicit ZLinks. If you have $ZROUTINES search lists that assume that explicit ZLINK would bypass your shared libraries, you should revise those in light of what you were trying to accomplish. (C9H11-002932)

    • [V5.3-001A] GT.M no longer generates unaligned access errors in the system log files. Previously, due to an incorrect size of a structure in 64-bit UNIX versions of GT.M, running the gtcm_gnp server could generate unaligned access messages. (C9I02-002959)

    • [V5.3-001A] An auto-ZLINKing process now holds control of a newly generated object file until it completes loading the fresh code from it. Previous versions used to close the newly created object file at the end of the compile and then reopen it to load the code - this left a small window where another process could delete that file and cause a somewhat mystifying file-not-found error. (C9I02-002960)

    • [V5.3-001A] GT.M now guards against signals interrupting time requests other than those for internal use. Previously limitations on reentrancy of UNIX services could occasionally cause time requests to hang if a signal resulted in another time request while one was already active. [UNIX] (C9I03-002967)

    • [V5.3-001A]GT.M now reports if it encounters errors or a full OPCOM mailbox while trying to send operator messages; it sends this report at the first non-failing attempt. It also retries sending an operator message for the mail box full condition. [OpenVMS] (C9I03-002969)

    • [V5.3-001A] GT.M now manages object files on some 64-bit platforms in a way that avoids a small memory leak that existed in prior versions. [Linux/IA64, Linux/x86_64, HPUX/IA64] (C9I03-002971)

    Return to top

    Utilities- MUPIP

    • [V5.3-001A] The source server now replicates data correctly whether it reads from journal files or the journal pool. In GT.M V5.3-001, if the source server needed to read from journal files and if the journal files had sync_io turned on and were using alignsize values greater than 64Kb, it read more data than its internal buffers could hold leading to memory corruption and mysterious abnormal termination. [UNIX] (S9I03-002675)

    • The GT.M utilities except GDE (DSE, LKE, MUPIP) now require arguments and values entered directly from the shell and containing single-quote (') or double-quotes (") to have the quotes "protected" by an escape mechanism. Each one must be preceded by a back-slash (\) or the entire string must be enclosed in a set of quotes (single or double) that do not also appear in the string. Previously GT.M attempted to implicitly escape quotes within some strings when it added quotes in preprocessing strings, but that prior approach led to inconsistent behavior in certain cases. The following are examples of appropriate usage:

         lke show -lock='^global("embed=and""nospace")'
   lke show -lock="^global(\"embedded\"\" quote\")"
   lke show -lock='^a("two words",5)'
-
      [Caution]
      This change may cause some existing scripts to fail.

      The following is an example from our test system where the old usage required revision:

      $MUPIP backup -o -i -t=1 DEFAULT "| gzip -c > online5pipe.inc.gz"

      Now must be:

      $MUPIP backup -o -i -t=1 DEFAULT "\"| gzip -c > online5pipe.inc.gz"\"

      Behavior at the utility prompt is unchanged. [UNIX] (D9G12-002633)

    • Backward journal recovery (MUPIP JOURNAL ROLLBACK or MUPIP JOURNAL RECOVER BACKWARD) now maintains the integrity of the master bitmap when the total blocks in the database is a multiple of 512. In previous versions, these operations could, in that case coupled with other unusual conditions, result in a database with a DBMBPINCFL integrity error (Master bitmap incorrectly marks this local map full). Please note that although no database integrity error is desirable, DBMBINCFL is a "benign" error whose only effect is wasted space in the database. (C9H10-002923)

    • MUPIP REORG now preserves application data integrity even in case of concurrent GT.M updates. In previous versions, running MUPIP REORG concurrently with GT.M could result in data loss in certain extremely rare cases. In GT.M V5.3-000 one particular case of this issue was addressed by C9B11-001813. Additional cases are addressed by this change. (C9H12-002934) -

    • [V5.3-001A] MUPIP INTEG now correctly reports a DBINVGBL integrity error when it finds records with one global name in the Global Variable Tree (GVT) belonging to a different global name. Previous GT.M versions used to miss reporting an integrity error in case the incorrectly placed records were in the rightmost leaf block of the target GVT and the global name corresponding to the incorrectly placed records lexically sorted AFTER the global name corresponding to the target GVT. For example, if MUPIP INTEG encountered records of ^AA in the rightmost leaf block of the GVT of ^BB, it issued (and continues to issue) an integrity error but if there were records of ^CC incorrectly placed in the rightmost leaf block of the GVT of ^BB, then INTEG previously issued no error. (C9I02-002956)

    Return to top

    Utilities-Other Than MUPIP

    +

    [Caution]
    This change may cause some existing scripts to fail.

    The following is an example from our test system where the old usage required revision:

    $MUPIP backup -o -i -t=1 DEFAULT "| gzip -c > online5pipe.inc.gz"

    Now must be:

    $MUPIP backup -o -i -t=1 DEFAULT "\"| gzip -c > online5pipe.inc.gz"\"

    Behavior at the utility prompt is unchanged. [UNIX] (D9G12-002633)

  • Backward journal recovery (MUPIP JOURNAL ROLLBACK or MUPIP JOURNAL RECOVER BACKWARD) now maintains the integrity of the master bitmap when the total blocks in the database is a multiple of 512. In previous versions, these operations could, in that case coupled with other unusual conditions, result in a database with a DBMBPINCFL integrity error (Master bitmap incorrectly marks this local map full). Please note that although no database integrity error is desirable, DBMBINCFL is a "benign" error whose only effect is wasted space in the database. (C9H10-002923)

  • MUPIP REORG now preserves application data integrity even in case of concurrent GT.M updates. In previous versions, running MUPIP REORG concurrently with GT.M could result in data loss in certain extremely rare cases. In GT.M V5.3-000 one particular case of this issue was addressed by C9B11-001813. Additional cases are addressed by this change. (C9H12-002934) +

  • [V5.3-001A] MUPIP INTEG now correctly reports a DBINVGBL integrity error when it finds records with one global name in the Global Variable Tree (GVT) belonging to a different global name. Previous GT.M versions used to miss reporting an integrity error in case the incorrectly placed records were in the rightmost leaf block of the target GVT and the global name corresponding to the incorrectly placed records lexically sorted AFTER the global name corresponding to the target GVT. For example, if MUPIP INTEG encountered records of ^AA in the rightmost leaf block of the GVT of ^BB, it issued (and continues to issue) an integrity error but if there were records of ^CC incorrectly placed in the rightmost leaf block of the GVT of ^BB, then INTEG previously issued no error. (C9I02-002956)

    • Return to top

    Utilities-Other Than MUPIP

    • None.

    -

    Return to top

    Error Messages

    Return to top

    GTMSECSHRTMPPATH

    GTMSECSHRTMPPATH: gtmsecshr path is pppp

    Information Message: GT.M displays this message when different users of an instance of GT.M connect using a socket or a semaphore and when gtmsecshr is started and it detects an existing gtmsecshr. pppp indicates the gtm_tmp path set in the clients. Gtmsecshr inherits the path from the first GT.M process that uses its services.

    Action: If different clients of the same instance of GT.M are using different gtmsecshr paths, then set a common value for the environment variable gtm_tmp for all users of an instance of GT.M, then stop and restart the processes that were using incorrect paths. If gtmsecshr itself has the incorrect path, all processes that are using that incorrect path must be stopped first - then stop gtmsecshr with a kill command.

    Return to top

    OPCOMMISSED [V5.3-001A]

    OPCOMMISSED n errors and m MBFULLs sending prior operator messages

    Informational Message: GT.M issues this message to the operator log if any operator messages prior to the immediately preceding one had not been sent due to errors from $SNDOPR. m is the number of time a persistent MBFULL error prevented a messages from being sent and n is the number of other errors whose reports were bypassed.

    Action: None.

    +

    Return to top

    Error Messages

    Return to top

    GTMSECSHRTMPPATH

    GTMSECSHRTMPPATH: gtmsecshr path is pppp

    Information Message: GT.M displays this message when different users of an instance of GT.M connect using a socket or a semaphore and when gtmsecshr is started and it detects an existing gtmsecshr. pppp indicates the gtm_tmp path set in the clients. Gtmsecshr inherits the path from the first GT.M process that uses its services.

    Action: If different clients of the same instance of GT.M are using different gtmsecshr paths, then set a common value for the environment variable gtm_tmp for all users of an instance of GT.M, then stop and restart the processes that were using incorrect paths. If gtmsecshr itself has the incorrect path, all processes that are using that incorrect path must be stopped first - then stop gtmsecshr with a kill command.

    Return to top

    OPCOMMISSED [V5.3-001A]

    OPCOMMISSED n errors and m MBFULLs sending prior operator messages

    Informational Message: GT.M issues this message to the operator log if any operator messages prior to the immediately preceding one had not been sent due to errors from $SNDOPR. m is the number of time a persistent MBFULL error prevented a messages from being sent and n is the number of other errors whose reports were bypassed.

    Action: None.

    For more information, see the GT.M web site.
    diff --git a/articles/GTM_V5.3-002_Release_Notes.html b/articles/GTM_V5.3-002_Release_Notes.html index 27603c6..93f6a58 100644 --- a/articles/GTM_V5.3-002_Release_Notes.html +++ b/articles/GTM_V5.3-002_Release_Notes.html @@ -98,7 +98,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    11.11

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

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) 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 (as root) can be used to determine if this patch has been applied. Note that recent "BATCH" and "GOLDEN" patches may contain this patch therefore your system may already have this patch applied but may not list it separately. Contact an HP service representative for more information.

    @@ -126,7 +126,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    Although AIX 5.2 and 5.3 are the officially supported releases, we are not aware of any reason why GT.M V5.3-002 will not run on AIX 6.x.

    -
    [Tip]
    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.
    +
    [Tip]
    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.

    Sun SPARC Solaris

    @@ -192,7 +192,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    4-byte

    gtm_uint_t has 32 bit length on all platforms

    -
    [Caution]
    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)

    +
    [Caution]
    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

    @@ -208,7 +208,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    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.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -224,7 +224,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    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.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. FIS will address this in a future release. (C9H10-002924)

    Return to top

    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 top

    Additional Installation Instructions

    For installing 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. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-002 in /opt/lsb-gtm/V5.3-002 on Linux systems.

    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 >.

      [Caution]
      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:

    • +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. FIS will address this in a future release. (C9H10-002924)

    Return to top

    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 top

    Additional Installation Instructions

    For installing 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. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-002 in /opt/lsb-gtm/V5.3-002 on Linux systems.

    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 >.

      [Caution]
      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 in one of the following modes:

    • smit aio (for gui mode) or @@ -251,7 +251,7 @@ gmake gmake check gmake install

    • 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.

    [Note]
    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.

    Return to top

    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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    Change History

    Fixes and enhancements specific to V5.3-002 are:

    S9D08-002359
    S9D11-002394
    S9F01-002523
    S9F06-002552
    S9H03-002644
    S9I03-002677
    S9I05-002681
    S9I05-002682
    S9I05-002686
    S9I06-002687
    S9I07-002688
    S9I07-002689
    S9I07-002690
    S9I07-002692
    C9C06-002064
    C9D07-002355
    C9D10-002413
    C9D12-002471
    C9E02-002525
    C9F03-002709
    C9F06-002736
    C9I01-002946
    C9I01-002947
    C9I01-002953
    C9I03-002972
    C9I04-002974
    C9I04-002975
    C9I04-002976
    C9I04-002977
    C9I05-002989
    C9I06-002998
    C9I06-003000
    C9I06-003002
    C9I06-003002
    C9I07-003006
    C9I07-003007
    C9I07-003009
    C9I08-003012

    Return to top

    M-Database Access

    • +

      • 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.

    Return to top

    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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

    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 top

    Change History

    Fixes and enhancements specific to V5.3-002 are:

    S9D08-002359
    S9D11-002394
    S9F01-002523
    S9F06-002552
    S9H03-002644
    S9I03-002677
    S9I05-002681
    S9I05-002682
    S9I05-002686
    S9I06-002687
    S9I07-002688
    S9I07-002689
    S9I07-002690
    S9I07-002692
    C9C06-002064
    C9D07-002355
    C9D10-002413
    C9D12-002471
    C9E02-002525
    C9F03-002709
    C9F06-002736
    C9I01-002946
    C9I01-002947
    C9I01-002953
    C9I03-002972
    C9I04-002974
    C9I04-002975
    C9I04-002976
    C9I04-002977
    C9I05-002989
    C9I06-002998
    C9I06-003000
    C9I06-003002
    C9I06-003002
    C9I07-003006
    C9I07-003007
    C9I07-003009
    C9I08-003012

    Return to top

    M-Database Access

    • GT.M journaling logic now recovers from additional runtime errors. If the control structures in the journal buffer (in database shared memory) get set to invalid values (such as unanticipated, out-of-design condition), GT.M journal buffer flushing logic detects this situation, turns OFF journaling right away and sends appropriate messages to the syslog (operator log in VMS). Subsequent updates to the database continue to work without any issues. Previous versions of GT.M used to hang for minutes trying to recover from this situation and terminate unlucky processes abnormally with GTMASSERT errors. In addition, processes could try writing to non-allocated portions of the journal file, which in turn caused a flood of JNLACCESS messages in the operator log. (S9D11-002394, S9I07-002690)

    • This release includes a field test grade implementation of the MM (Mapped Memory) database access method for UNIX/Linux. The OpenVMS editions of GT.M previously supported MM and continue to do so unchanged. The MM access method maps database files (with the mmap() system call) to the address space of all processes accessing the corresponding MM region, thereby using the operating system to manage traffic between memory and disk rather than using the global buffer pool as in the Buffered Global (BG) access method. Note that before image journaling and backward recovery require that before-image journal records be committed to disk before the corresponding database updates are committed. Since this is not possible with MM, before-image journaling, and consequently mupip backward recovery/rollback to recover a database without a restore are not available with MM. Attempts to use MM with before image journaling produce an error. The MM access method supports nobefore_image journaling and mupip forward recovery, as well as mupip journal rollback with the -resync or -fetchresync qualifiers to generate lost and broken transaction files. The implementation of MM on UNIX/Linux allows databases to extend dynamically, as they do with BG; as before, the implementation of MM on OpenVMS does not permit dynamic database file extension. The MM access method may provide a performance advantage in situations where its restrictions are acceptable. Although we do not yet recommend this feature in production (the next GT.M release will make MM fully Supported), we encourage you to try it in appropriate development, testing and benchmarking environments and to tell us how it works for you – especially about any issues you encounter and any performance gain you experience. Note that the field test designation refers only to the new MM access method for UNIX/Linux. V5.3-002, including MM for OpenVMS, is a fully tested and qualified, production grade GT.M release that is at least as robust as, if not more robust than, any previous GT.M release. [UNIX] (C9904-001024)

    • The Linux version of GT.M can now utilize O_DIRECT support for journal files. The O_DIRECT option is made available by using the sync_io option to the MUPIP SET -JOURNAL command just as for the other platforms that support direct I/O. [Linux] (C9D10-002409)

    • The 'VIEW "FLUSH"' (originally introduced in V5.0-000), now always flushes all dirty buffers from the global buffer pool. Previous versions might only do a partial flush. (C9E02-002525)

    • diff --git a/articles/GTM_V5.4-002_Release_Notes.html b/articles/GTM_V5.4-002_Release_Notes.html index 0c01c40..64db7d1 100644 --- a/articles/GTM_V5.4-002_Release_Notes.html +++ b/articles/GTM_V5.4-002_Release_Notes.html @@ -42,7 +42,7 @@ gtmsupport@fisglobal.com
      JNLTPNEST

      REPLJNLCNFLCT
      REPLNOXENDIAN
      - REPLNOMULTILINETRG [V5.4-002A]
      + REPLNOMULTILINETRG [V5.4-002A]
      REPLXENDIANFAIL
      SECNODZTRIGINTP
      SETINSETTRIGONLY
      SHMREMOVED [V5.4-002B]
      @@ -53,7 +53,7 @@ gtmsupport@fisglobal.com
      TRIGNAMBAD
      TRIGNAMENF
      TRIGZBREAKREM
      - WRITEWAITPID
      ZCCLNUPRTNMISNG [V5.4-002B]
      ZCINVALIDKEYWORD [V5.4-002B]
      ZGOCALLOUTIN
      ZGOTOINVLVL2

    Conventions

    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 "/" rather than a "-".

    Program Names: When referring to a GT.M program or function, the reference is in upper case, for example, MUPIP BACKUP. When a specific example is provided, the lower case UNIX command names are used, for example, 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 [].

    In GT.M documentation, we're adopting the terms "originating instance" where we previously used "primary instance" or "originating primary instance," and the term "replicating instance" where we previously used "secondary instance" and "originating secondary instance." 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.

    GT.M runs on a wide variety of UNIX/Linux implementations as well as OpenVMS. Consult FIS for currently supported versions. Each GT.M release is extensively tested by FIS on a set of specific versions of operating systems on specific hardware architectures (the combination of operating system and hardware architecture is referred to as a platform). This set of specific versions is considered Supported. There will be other versions of the same operating systems on which a GT.M release may not have been tested, but on which the FIS GT.M support team knows of no reason why GT.M would not work. This larger set of versions is considered Supportable. There is an even larger set of platforms on which GT.M may well run satisfactorily, but where the FIS GT.M team lacks the knowledge to determine whether GT.M is Supportable. These are considered Unsupported. Contact FIS GT.M Support with inquiries about your preferred platform.

    Release Overview

    GT.M V5.4-002B provides timely remediation of some additional issues with V5.4-002 and V5.4-002A (highlighted as [V5.4-002B]).

    GT.M V5.4-002A provides timely remediation of some issues with V5.4-002 (highlighted as [V5.4-002A]).

    GT.M V5.4-002 brings performance and scalability enhancements to GT.M:

    • The previous implementation of local variables has been replaced by one that scales well to large numbers of nodes at a given subscript level. FIS has internally validated its scalability to over one million nodes and also validated that it preserves or even slightly improves upon GT.M's traditional fast performance for local variables with smaller numbers of nodes.

    • On 64-bit editions of GT.M, the previous per-region limits of 65,536 global buffers and 2GB shared segment size are no longer limited by GT.M; of course, they remain limited by your actual computing platform.

    There are important enhancements to the trigger facility:

    • Trigger -xecute commands can span multiple lines.

    • The new ZTRIGGER command allows a trigger to be explicitly invoked under program control.

    • $ZTNAME replaces the deprecated $ZTCODE in the trigger signature.

    • The use of $ZTRIGGER() within a TP transaction allows trigger logic to be updated atomically within a transaction. Some restrictions apply.

    An "unlink all" capability for UNIX platforms allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref at the top of the stack; local variables and IO devices are preserved across the transition.

    A new option generates code to evaluate elements of Boolean expressions in an alternative order that ensures expresion components with side effects evluated before the Boolena evaluation as an alternative to GT.M's default behavior which stops the evaluation of Boolean expressions once the final outcome is determined.

    Please refer to the description of C9K09-003324 for changes to the configure script used to install GT.M.

    V5.4-002 contains numerous fixes, remedied mis-features, and smaller enhancements. For a comprehensive list, refer to Change History.

    Conventions

    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 "/" rather than a "-".

    Program Names: When referring to a GT.M program or function, the reference is in upper case, for example, MUPIP BACKUP. When a specific example is provided, the lower case UNIX command names are used, for example, 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 [].

    In GT.M documentation, we're adopting the terms "originating instance" where we previously used "primary instance" or "originating primary instance," and the term "replicating instance" where we previously used "secondary instance" and "originating secondary instance." 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.

    GT.M runs on a wide variety of UNIX/Linux implementations as well as OpenVMS. Consult FIS for currently supported versions. Each GT.M release is extensively tested by FIS on a set of specific versions of operating systems on specific hardware architectures (the combination of operating system and hardware architecture is referred to as a platform). This set of specific versions is considered Supported. There will be other versions of the same operating systems on which a GT.M release may not have been tested, but on which the FIS GT.M support team knows of no reason why GT.M would not work. This larger set of versions is considered Supportable. There is an even larger set of platforms on which GT.M may well run satisfactorily, but where the FIS GT.M team lacks the knowledge to determine whether GT.M is Supportable. These are considered Unsupported. Contact FIS GT.M Support with inquiries about your preferred platform.

    Release Overview

    GT.M V5.4-002B provides timely remediation of some additional issues with V5.4-002 and V5.4-002A (highlighted as [V5.4-002B]).

    GT.M V5.4-002A provides timely remediation of some issues with V5.4-002 (highlighted as [V5.4-002A]).

    GT.M V5.4-002 brings performance and scalability enhancements to GT.M:

    • The previous implementation of local variables has been replaced by one that scales well to large numbers of nodes at a given subscript level. FIS has internally validated its scalability to over one million nodes and also validated that it preserves or even slightly improves upon GT.M's traditional fast performance for local variables with smaller numbers of nodes.

    • On 64-bit editions of GT.M, the previous per-region limits of 65,536 global buffers and 2GB shared segment size are no longer limited by GT.M; of course, they remain limited by your actual computing platform.

    There are important enhancements to the trigger facility:

    • Trigger -xecute commands can span multiple lines.

    • The new ZTRIGGER command allows a trigger to be explicitly invoked under program control.

    • $ZTNAME replaces the deprecated $ZTCODE in the trigger signature.

    • The use of $ZTRIGGER() within a TP transaction allows trigger logic to be updated atomically within a transaction. Some restrictions apply.

    An "unlink all" capability for UNIX platforms allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref at the top of the stack; local variables and IO devices are preserved across the transition.

    A new option generates code to evaluate elements of Boolean expressions in an alternative order that ensures expresion components with side effects evluated before the Boolena evaluation as an alternative to GT.M's default behavior which stops the evaluation of Boolean expressions once the final outcome is determined.

    Please refer to the description of C9K09-003324 for changes to the configure script used to install GT.M.

    V5.4-002 contains numerous fixes, remedied mis-features, and smaller enhancements. For a comprehensive list, refer to Change History.

    Platforms

    Over time, computing platforms evolve. Vendors obsolete hardware architectures. New versions of operating systems replace old ones. We at FIS continually evaluate platforms and versions of platforms that should be Supported for GT.M. In the table below, we document not only the ones that are currently Supported for this release, but also alert you to our future plans given the evolution of computing platforms. If you are an FIS customer, and these plans would cause you hardship, please contact your FIS account executive promptly to discuss your needs.

    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

    		 @@ -478,7 +478,7 @@ key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    MUMPS

    KILL * corrections

    -

    These fixes are marked with [V5.4-002A] in the subsequent sections.

    +

    These fixes are marked with [V5.4-002A] in the subsequent sections.

    V5.4-002

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

    CR#

    		 @@ -1171,10 +1171,10 @@ GTM>ztrigger ^C

    YES*

    YES*

    -

    RI means replicating instance and OI means originating instance;OpenVMS+ can act as RI only to same-endian instance in dual site mode.

    * ? means FIS does not test this configuration, but it might work because the conversion can occur on the replicating instance.

    * means if the replicating instance does not support triggers the originating instance sends updates performed by triggers, but no updates to triggers themselves.

    In a cross-endian environment, V5.4-000[A] and V5.4-001 do not work correctly when replicating updates from originating instances with higher GT.M versions (V5.4-002 and above) (C9K09-003326)

  • GT.CM GNP server honors MUPIP STOP (SIG-15), at the first opportunity, even if the signal arrives while GT.CM server is executing a non-interruptible code path. Previously in such cases, the server might lose track of MUPIP STOP, ignore the interrupt, and just continue waiting for client requests. [UNIX] (C9K09-003327)

  • GT.M appropriately defers timer interrupts (for example, database flush timers) to prevent an out-of-design state. Previously in a rare situation, an interrupt could cause a process to terminate with a fatal GTMASSERT (in module have_crit.c). [UNIX] (C9K10-003335)

  • GT.M appropriately handles an unusual situation where the rate of change in journal files exceeds the rate of journal file writes in some process. In prior versions, a such a process might not recognize it needed to change journal files when it should and could cause a database stall of up to two minutes. [UNIX] (C9K11-003339)

  • [V5.4-002A] GT.M ensures that journal records are never written with out-of-order timestamps. Previously, in rare cases where the system time went back by a second or two, GT.M wrote journal records with out-of-order timestamps which could cause MUPIP JOURNAL -RECOVER to fail. Note that even previously GT.M generally protected itself against the eventuality of the system clock going backwards; the fix remedied a rare code path where it did not. Note also that FIS recommends against stepping the system clock back when GT.M applications are active - slewing the clock is safe and is the preferred option when GT.M applications are active. (C9K12-003350)

  • GT.M includes the journal sequence number (token sequence number if replication is not enabled) field of all replicated records as part of computing the checksum of the journal record. Previously, this field was not a part of the checksum and in rare cases, after a crash, could cause ROLLBACK/RECOVERY to assume a bad journal record to be a good one resulting in GTM-F-MEMORY errors. [UNIX] (C9L01-003354)

  • [V5.4-002A] A database access during the "final" retry (third or higher) of a TP transaction from an error handler specified by $ETRAP works correctly. Previously, such a combination damaged internal data structures that would most likely result in process termination with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). As the damage produced incorrect addresses, its effect could not be guaranteed, and although unlikely, could in theory cause the affected process to produce incorrect results or database damage. (C9L03-003368)

  • During replication, the GT.M Source Server handles certain timeout related network stress as connection resets, that is: the Source Server breaks its connection with the Receiver Server and attempts to reconnect. Previously, these timeouts caused the Source Server to exit. While FIS was not able to recreate these network conditions in the GT.M development environment, GT.M includes changes that should make it more robust in the face of these not-yet-characterized network timeouts. (C9L03-003369)

  • [V5.4-002A] GT.M deals appropriately with an unusual set of circumstances where: the global directory contains a -KEY_SIZE less than the maximum key size in database file header and the application does a VIEW "NOISOLATION" on one or more globals in the region before the first reference to any global in the region. The global directory and the database file header might not match if the current global directory was not used to create the database file or if the file header was modified with DSE. Previously this caused a GTMASSERT. The workarounds were to avoid the mismatch between the global directory and the database or to access at least one global in the region before issuing the VIEW "NOISOLATION" command. (C9L03-003393)

  • [V5.4-002A] MERGE gvn=glvn sets $REFERENCE and the "naked indicator" to gvn even if the glvn has a $DATA() result of 0. Previously this unusual condition left $REFERENCE to either its prior value if the source was an lvn or to reflect the source gvn if it was a global. (C9L03-003394)

  • [V5.4-002B] GT.M correctly handles runtime errors for a SET or $INCREMENT() of a gvn. Previously, such errors in very rare cases could result in database damage. (C9L04-003407)

  • [V5.4-002B] GT.M follows a GVSUBOFLOW error message with a GVIS message with a * at the end of the global variable node to indicate incompleteness. For example, if a program attempts a SET^ZGBL(1,2) and the maximum key size for the region is 10, the GVIS message reports ^ZGBL(1* as the global variable to indicate that the reported value is incomplete and that the actual value could contain zero or more subscripts replacing the *. GT.M previously reported a GVIS message with ^ZGBL(1) as the global variable to indicate that the maximum key size was exceeded while processing the second subscript. In addition, a GVSUBOFLOW in a string subscript containing either $C(0) or $C(1) no longer reports garbled subscript values of arbitrary length. (C9L05-003412)

  • [V5.4-002B] NOBEFORE_IMAGE journaling avoids a potentially time consuming action that has no value to its successful operation. Although the change affects both BG and MM access methods, the impact is likely to be greater with MM. (C9L06-003429)

  • [V5.4-002B] GT.M now explicitly enforces ordering for a few additional shared memory operations used in the course of buffer management in the database logic. While we are not currently aware of any issues in production sites, our testing revealed that, at least on some IBM pSeries systems, aggressive instruction reordering could cause out-of-order store order conditions that violate the design and raise the possibility of database damage. Note that the x86 (both 32- and 64-bit) and zSeries do not create out-of-order store conditions, nor does the p6 (the p5 and p7 do); other platforms can generate such conditions with varying degrees of frequency. (C9L07-003437)

    • - M-Other Than Database Access

    • ZGOTO accepts a negative level and treats it as $zlevel-intexpr. In prior versions, negative arguments produced a ZGOTOLTZERO error. GT.M handles all identified ZGOTO cases correctly, including ZLINKFILE, INVOBJ, MEMORY (exhausted), GTMASSERT errors and various signals on UNIX and ACCVIOs on OpenVMS. (S9606-000216, C9D06-002318, C9H04-002845)

    • GT.M handles numeric strings which are not canonical within the implementation as strings unless the application specifically requests they be treated as numbers. Any use in a context defined as numeric elicits numeric treatment; this includes operands of numeric operators, numeric literals, and some intrinsic function arguments. When the code creates a large number out of range , GT.M gives a NUMOFLOW error. When the code creates a small fractional number out of range GT.M treats it as zero (0). The GT.M number range is (to the limit of accuracy) 1E-43 to 1E47. When the application creates an in-range number that exceeds the GT.M numeric accuracy of 18 significant digits, GT.M silently retains the most significant digits. With standard collation, GT.M collates canonic numeric strings used as subscripts numerically, while it collates non-canonic numbers as strings. Prior versions followed this pattern but had some edge case anomalies including:

      1. Sorts-after (]]) comparisons involving a number inappropriately treated some non-canonic strings as numbers

      2. $DATA() treated large out-of-range non-canonic numeric string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      3. $ORDER() of a local array containing a non-canonic decimal fraction with no integer part returned a numeric value which could cause indefinite looping

      4. $QUERY() with an argument specifying a local array treated large out-of-range non-canonic string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      5. In local arrays but not global arrays, MERGE treated non-canonic numeric string subscripts in as numbers, resulting in asymmetric merges

      6. ZWRITE treated non-canonic numeric string subscripts as numbers and, as a result, misrepresented such results

      7. GT.M did not treat calculations producing small out-of-range decimal values uniformly when they underflowed so tiny values that should have been the same could differ for example: (X+X) ‘= (2*X) for some very, very small values of X.

      8. Depending on context, GT.M reported numeric overflow at slightly differing values close to 1E47

      9. $NEXT(), which is deprecated, handles a constructed string that evaluates to -1 as a "starting value" and therefore picks up large negative subscripts (S9D06-002331, S9F05-002547, C9H02-002826)

    • [V5.4-002A] The new ZHALT command extends the HALT command to allow a GT.M process to provide a return code to the shell (or other process) from which it was invoked. The syntax of the command is ZHALT[:tvexpr] [intexpr]. GT.M returns the value of intexpr to the invoking program as the completion status. Since UNIX limits return codes to zero through 255, GT.M returns the return code modulo 256, unless the return code is non-zero but the value modulo 256 is zero, in which case GTM returns a (non-success) value of 255 so that the return code is non-zero. On OpenVMS, GT.M returns the standard success value (EXIT_SUCCESS or 1) if the ZHALT argument is zero and otherwise returns the standard failure value (EXIT_FAILURE or %X10000002). (S9J10-002744)

    • PIPE and FIFO devices respond to interrupts such as MUPIP INTRPT when waiting on a READ. Previously these devices ignored such interrupts while waiting on a READ. In direct mode, <CTRL-C> terminates a hung FIFO READ. Previously a FIFO device ignored a <CTRL-C> waiting on a READ. The direct mode behavior of the PIPE device remains the same, where a <CTRL-C> terminates PIPE subprocesses and the READ.

      The FIFO device correctly returns partial input for timed READs and sets status variables appropriately for fixed and UTF -8 mode READs. Previously a FIFO could hang and/or return partial data and/or not set status variables correctly for such READs.

      On z/OS, a readonly FIFO OPENs correctly and maintains $X properly. Previously on z/OS, readonly FIFO OPEN and $X misbehaved. [UNIX] (S9K02-002753)

    • READ from a SOCKET device provides improved protection against interrupts (for example, generated with MUPIP INTRPT). In prior releases, we had reports of segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Since FIS was unable to recreate these problems in the GT.M development environment, FIS cannot confirm whether they are entirely corrected. (S9K05-002770)

    • The jump optimizer in the GT.M compiler correctly optimizes the generated code in an obscure case. This issue started with V5.2-000 in certain 32-bit versions. While it is possible there are others, the only known condition to manifest symptoms is as follows: two nested argumentless DOs terminating on the same line where the inner DO preceded an argumentless FOR command on the same line containing no local variable references did not properly iterate. The only currently shipping version that showed this issue is x86 Linux, but 32-bit Solaris through V5.3-001A also might exhibit this problem. The workarounds for the identified symptom are to use an explicit QUIT or other code to avoid multiple argumentless DOs from terminating on the same line or ensure any line with a nested argumentless DO contains at least one local variable reference.[32-bit x86 Linux and 32-bit SPARC Solaris] (S9K07-002782).

    • GT.M local variable processing avoids occasional duplicate subscripts in local variable arrays. This addresses an interaction between GT.M and some versions of a C library (crtl) function. The code in question has been in GT.M for all versions and all platforms for a very long time (at least before V4.0-000). Even though this issue has only been reported on Linux x86 (32 bit) systems on V5.4-001, FIS believes that it is very hardware dependent and rare. It is also theoretically possible for this to manifest itself as a segmentation violation (SIG-11) on certain (usually older) x86 architecture CPUs, but FIS was was never able to replicate this in the GT.M development environment (S9K10-002786)

    • [V5.4-002A] M-profiling counts all types of FOR loops appropriately, and captures time consistently. When nesting levels exceed the facility's capacity to retain information, M-profiling stops detailed reporting and reports all subsequent time as a total. Previously FOR iterations were miscounted or not reported, and times could be very inaccurate; high levels of nesting could cause time capture to stop and restart with no accounting for the time between. M-profiling cannot and does not provide exact time information, but does provide a useful representation of where application code spends CPU cycles. Relative times reported by M-profiling should be meaningful. (S9L03-002804)

    • [V5.4-002A] The compiler gives FULLBOOLWARN warnings only in cases where the evaluation contains an AND (&) or an OR (!) with a $increment(), extrinsic function, or external call in other than the first element. In V5.4-002, it gave inappropriate warnings even in these cases where the side effect items are always evaluated. (S9L03-002807)

    • [V5.4-002B] $QLENGTH() and $QSUBSCRIPT() accept the non-standard (square-bracket) form of extended reference. Previously they only accepted the standard (up-bar) form. (S9L06-002813)

    • [V5.4-002B] GT.M handles job interrupts inside of a TP transaction more robustly. This fixes a regression introduced in V5.4-000, where a job interrupt that occurs inside a TP transaction that has not yet done any global reference but does some global reference inside the job interrupt code causing the first global reference after retunr from the job interrupt code to abnormally terminate with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) error. Note this abnormal termination could not affect database integrity. (S9L06-002816)

    • [V5.4-002B] $QSUBSCRIPT() returns a correct value when the selected subscript is exactly 0 (zero). Starting in V5.4-001, selecting a 0 subscript caused $QSUBSCRIPT() to return not only the 0 but all subsequent subscripts in the name. (S9L06-002820)

    • [V5.4-002B] $ZCONVERT() issues an ICUERROR error when ICU returns an inappropriate or unexpected error. Previously the process terminated with a GTMASSERT. [UNIX](S9L06-002821)

    • [V5.4-002B] VIEW "TRACE" works with triggers and call-ins. Previously, use of the VIEW "TRACE" facility with triggers or call-ins resulted in a GTMASSERT. [UNIX] (S9L06-002822)

    • ZWRITE accepts Intrinsic Special Variables (ISVs) as single arguments. This provides a way to easily expose non-graphic characters in individual ISVs. ISVs cannot be selected with the pattern matching and range syntax that ZWRITE accepts for global and local variables. As before, ZSHOW "I" provides a way to get all ISVs. In previous versions ZWRITE did not permit ISV arguments. (C9806-000511)

    • GT.M has a completely new implementation of local variables that scales much better for local variables with large numbers of nodes while preserving or even slightly improving upon the fast performance of local variables with small number of nodes that the previous implementation handled well. The new implementation outperforms global variables at all sizes tested, even local variables with hundreds of thousands of nodes. For local variables with more than a few thousand nodes, global variables outperformed the prior implementation. There is no functional difference.

      This refactoring effort also improved some other aspects of performance.

      The gtm_lvscale environment variable previously available to tune local variable structures is now ignored. You can safely let it remain in shell scripts that are designed to span GT.M versions with both local variable implementations.

      As part of the same effort, $QUERY() with standard NULL collation no longer skips descendants of an empty string subscript.

      Also as part of this effort, GT.M uniformly enforces the rule that a collation transform (or reverse transform) cannot modify an empty string ("NULL") subscript. In prior versions some, but not all operations enforced this rule, which applies to global variables as well as local variables. Note that transforms should not introduce empty string subscripts and GT.M does not currently protect against this. (C9905-001087)

    • An attempt to use a subscripted FOR control variable and calculate values assigned to it using expressions with side effects generates a FORCTRLINDX error. This construct presents some issues that can potentially cause incorrect results or segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Previous releases did not guard against this problem. Note GT.M does not detect the loss of a control variable specified by indirection and then destroyed within scope (by a KILL or NEW) and when it detects the loss of an unsubscripted indirect control variable does not report the name of that variable. FIS recommends against such usage as a source of program fragility; refer to C9L03-003392. (C9B03-001660)

    • GT.M provides an option to control evaluation of Boolean expressions (expressions evaluated as a logical TRUE or FALSE). By default, GT.M stops evaluating such expression as soon as it establishes a definitive result. For example, in this mode, neither 0&$$abc^def() or 1!$$abc^def() ever executes $$abc^def(). In the case of global references, such as 0&^a or 1!^a, GT.M correctly sets $Reference and the naked indicator without actually accessing the global variable.

      The settings may be altered with a VIEW command using an argument evaluating to (case-insensitive) "FULL_BOOLEAN" to select a evaluation order that evaluates expression atoms with short-circuit side effects prior to Boolean evaluation: "NOFULL_BOOLEAN" to select the traditional GT.M evaluation order which stops as soon as the result is known, and "FULL_BOOLWARN" which evaluates like "FULL_BOOLEAN" but also produces a BOOLSIDEFFECT warning when it encounters Boolean expressions that may induce side-effects; that is: expressions with side effects after the first Boolean operator - extrinsic functions, external calls and $INCREMENT(). The new gtm_boolean environment variable (UNIX) or GTM_BOOLEAN logical name (OpenVMS) provide initial values to control this behavior at process startup. If gtm_boolean is undefined or evaluates to an integer zero (0), the initial setting the default "NOFULL_BOOLEAN", if it evaluates to an integer one (1), the initial setting is "FULL_BOOLEAN" and if it evaluates to integer two (2) the initial setting is "FULL_BOOLWARN". Other numeric values are reserved for possible future controls - do not use them.

      These are compilation settings and the object code determines run-time execution independent of the current setting. As changing the compiler setting does not clear previously compiled and cached XECUTE arguments, changing the setting before an XECUTE may or may not produce a desired effect. "FULL_BOOLWARN" does not produce warnings on XECUTE arguments with potential side effects in Boolean evaluation.

      $VIEW("FULL_BOOLEAN") returns a string describing the current compiler setting.Note that while the FULL_BOOLEAN setting ensures that the side-effect expression atoms execute, it does not produce results that match full left-to-right evaluation in cases where the side-effect operation alters variables that appear before it in the Boolean expression. Therefore it's prudent to use the FULL_BOOLWARN setting to identify and evaluate and appropriately adjust the use of side-effect expression atoms in Boolean expressions.

      GT.M does not short-circuit evaluation if the first argument of a $INCREMENT() uses indirection. In prior releases, GT.M always compiled in "NOFULL_BOOLEAN" order, but exhibited inappropriate behavior when the first argument to $INCREMENT() used indirection, including spurious VAREXPECTED errors with no variable named by the error message, and incorrectly maintained $REFERENCE (and the naked indicator) when it skipped a $INCREMENT() both of whose arguments were global variables. If your application uses indirection for the first argument of $INCREMENT() in Boolean expressions, please analyze and test those instances thoroughly.

      Note that in the default short-circuit mode, global references within an extrinsic function are not reflected in the $REFERENCE of the caller, regardless of whether or not the extrinsic actually executes - this behavior is unchanged. (C9B04-001673)

    • Call ins offer a gtm_cip() interface, similar to gtm_ci() but using a handle, which improves performance on calls after the first one. gtm_cip() replaces the first argument of gtm_ci() with an argument of type struct ci_name_descriptor which contains the routine name and a handle to the call in function. GT.M populates the empty handle on the first call; the caller must not modify the handle (or bad things happen). Prior versions only offered the original gtm_ci() interface. This change also improved the performance of the original gtm_ci() interface. [UNIX] (C9D07-002340),

    • The gtm_exit call for GT.M call-ins cleans up any pending timers setup using the gt_timers interface and releases all associated memory. Previously, gtm_exit could leak a modest amount of memory used to track the timers. [UNIX](C9E12-002687)

    • $ZDATE() provides a date representation for day 0 (31-Dec-1840) and accepts two to six consecutive "Y" characters to indicate digits of year. Previously, $ZDATE() only accepted "YY" and "YEAR" to indicate two- and four-digit years respectively, and $ZDATE() of zero (0) produced an empty output. For example:

      GTM>write $zdate(123456789,"DAY MON DD, YYYYYY") 
+

    RI means replicating instance and OI means originating instance;OpenVMS+ can act as RI only to same-endian instance in dual site mode.

    * ? means FIS does not test this configuration, but it might work because the conversion can occur on the replicating instance.

    * means if the replicating instance does not support triggers the originating instance sends updates performed by triggers, but no updates to triggers themselves.

    In a cross-endian environment, V5.4-000[A] and V5.4-001 do not work correctly when replicating updates from originating instances with higher GT.M versions (V5.4-002 and above) (C9K09-003326)

  • GT.CM GNP server honors MUPIP STOP (SIG-15), at the first opportunity, even if the signal arrives while GT.CM server is executing a non-interruptible code path. Previously in such cases, the server might lose track of MUPIP STOP, ignore the interrupt, and just continue waiting for client requests. [UNIX] (C9K09-003327)

  • GT.M appropriately defers timer interrupts (for example, database flush timers) to prevent an out-of-design state. Previously in a rare situation, an interrupt could cause a process to terminate with a fatal GTMASSERT (in module have_crit.c). [UNIX] (C9K10-003335)

  • GT.M appropriately handles an unusual situation where the rate of change in journal files exceeds the rate of journal file writes in some process. In prior versions, a such a process might not recognize it needed to change journal files when it should and could cause a database stall of up to two minutes. [UNIX] (C9K11-003339)

  • [V5.4-002A] GT.M ensures that journal records are never written with out-of-order timestamps. Previously, in rare cases where the system time went back by a second or two, GT.M wrote journal records with out-of-order timestamps which could cause MUPIP JOURNAL -RECOVER to fail. Note that even previously GT.M generally protected itself against the eventuality of the system clock going backwards; the fix remedied a rare code path where it did not. Note also that FIS recommends against stepping the system clock back when GT.M applications are active - slewing the clock is safe and is the preferred option when GT.M applications are active. (C9K12-003350)

  • GT.M includes the journal sequence number (token sequence number if replication is not enabled) field of all replicated records as part of computing the checksum of the journal record. Previously, this field was not a part of the checksum and in rare cases, after a crash, could cause ROLLBACK/RECOVERY to assume a bad journal record to be a good one resulting in GTM-F-MEMORY errors. [UNIX] (C9L01-003354)

  • [V5.4-002A] A database access during the "final" retry (third or higher) of a TP transaction from an error handler specified by $ETRAP works correctly. Previously, such a combination damaged internal data structures that would most likely result in process termination with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). As the damage produced incorrect addresses, its effect could not be guaranteed, and although unlikely, could in theory cause the affected process to produce incorrect results or database damage. (C9L03-003368)

  • During replication, the GT.M Source Server handles certain timeout related network stress as connection resets, that is: the Source Server breaks its connection with the Receiver Server and attempts to reconnect. Previously, these timeouts caused the Source Server to exit. While FIS was not able to recreate these network conditions in the GT.M development environment, GT.M includes changes that should make it more robust in the face of these not-yet-characterized network timeouts. (C9L03-003369)

  • [V5.4-002A] GT.M deals appropriately with an unusual set of circumstances where: the global directory contains a -KEY_SIZE less than the maximum key size in database file header and the application does a VIEW "NOISOLATION" on one or more globals in the region before the first reference to any global in the region. The global directory and the database file header might not match if the current global directory was not used to create the database file or if the file header was modified with DSE. Previously this caused a GTMASSERT. The workarounds were to avoid the mismatch between the global directory and the database or to access at least one global in the region before issuing the VIEW "NOISOLATION" command. (C9L03-003393)

  • [V5.4-002A] MERGE gvn=glvn sets $REFERENCE and the "naked indicator" to gvn even if the glvn has a $DATA() result of 0. Previously this unusual condition left $REFERENCE to either its prior value if the source was an lvn or to reflect the source gvn if it was a global. (C9L03-003394)

  • [V5.4-002B] GT.M correctly handles runtime errors for a SET or $INCREMENT() of a gvn. Previously, such errors in very rare cases could result in database damage. (C9L04-003407)

  • [V5.4-002B] GT.M follows a GVSUBOFLOW error message with a GVIS message with a * at the end of the global variable node to indicate incompleteness. For example, if a program attempts a SET^ZGBL(1,2) and the maximum key size for the region is 10, the GVIS message reports ^ZGBL(1* as the global variable to indicate that the reported value is incomplete and that the actual value could contain zero or more subscripts replacing the *. GT.M previously reported a GVIS message with ^ZGBL(1) as the global variable to indicate that the maximum key size was exceeded while processing the second subscript. In addition, a GVSUBOFLOW in a string subscript containing either $C(0) or $C(1) no longer reports garbled subscript values of arbitrary length. (C9L05-003412)

  • [V5.4-002B] NOBEFORE_IMAGE journaling avoids a potentially time consuming action that has no value to its successful operation. Although the change affects both BG and MM access methods, the impact is likely to be greater with MM. (C9L06-003429)

  • [V5.4-002B] GT.M now explicitly enforces ordering for a few additional shared memory operations used in the course of buffer management in the database logic. While we are not currently aware of any issues in production sites, our testing revealed that, at least on some IBM pSeries systems, aggressive instruction reordering could cause out-of-order store order conditions that violate the design and raise the possibility of database damage. Note that the x86 (both 32- and 64-bit) and zSeries do not create out-of-order store conditions, nor does the p6 (the p5 and p7 do); other platforms can generate such conditions with varying degrees of frequency. (C9L07-003437)

    • + M-Other Than Database Access

    • ZGOTO accepts a negative level and treats it as $zlevel-intexpr. In prior versions, negative arguments produced a ZGOTOLTZERO error. GT.M handles all identified ZGOTO cases correctly, including ZLINKFILE, INVOBJ, MEMORY (exhausted), GTMASSERT errors and various signals on UNIX and ACCVIOs on OpenVMS. (S9606-000216, C9D06-002318, C9H04-002845)

    • GT.M handles numeric strings which are not canonical within the implementation as strings unless the application specifically requests they be treated as numbers. Any use in a context defined as numeric elicits numeric treatment; this includes operands of numeric operators, numeric literals, and some intrinsic function arguments. When the code creates a large number out of range , GT.M gives a NUMOFLOW error. When the code creates a small fractional number out of range GT.M treats it as zero (0). The GT.M number range is (to the limit of accuracy) 1E-43 to 1E47. When the application creates an in-range number that exceeds the GT.M numeric accuracy of 18 significant digits, GT.M silently retains the most significant digits. With standard collation, GT.M collates canonic numeric strings used as subscripts numerically, while it collates non-canonic numbers as strings. Prior versions followed this pattern but had some edge case anomalies including:

      1. Sorts-after (]]) comparisons involving a number inappropriately treated some non-canonic strings as numbers

      2. $DATA() treated large out-of-range non-canonic numeric string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      3. $ORDER() of a local array containing a non-canonic decimal fraction with no integer part returned a numeric value which could cause indefinite looping

      4. $QUERY() with an argument specifying a local array treated large out-of-range non-canonic string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      5. In local arrays but not global arrays, MERGE treated non-canonic numeric string subscripts in as numbers, resulting in asymmetric merges

      6. ZWRITE treated non-canonic numeric string subscripts as numbers and, as a result, misrepresented such results

      7. GT.M did not treat calculations producing small out-of-range decimal values uniformly when they underflowed so tiny values that should have been the same could differ for example: (X+X) ‘= (2*X) for some very, very small values of X.

      8. Depending on context, GT.M reported numeric overflow at slightly differing values close to 1E47

      9. $NEXT(), which is deprecated, handles a constructed string that evaluates to -1 as a "starting value" and therefore picks up large negative subscripts (S9D06-002331, S9F05-002547, C9H02-002826)

    • [V5.4-002A] The new ZHALT command extends the HALT command to allow a GT.M process to provide a return code to the shell (or other process) from which it was invoked. The syntax of the command is ZHALT[:tvexpr] [intexpr]. GT.M returns the value of intexpr to the invoking program as the completion status. Since UNIX limits return codes to zero through 255, GT.M returns the return code modulo 256, unless the return code is non-zero but the value modulo 256 is zero, in which case GTM returns a (non-success) value of 255 so that the return code is non-zero. On OpenVMS, GT.M returns the standard success value (EXIT_SUCCESS or 1) if the ZHALT argument is zero and otherwise returns the standard failure value (EXIT_FAILURE or %X10000002). (S9J10-002744)

    • PIPE and FIFO devices respond to interrupts such as MUPIP INTRPT when waiting on a READ. Previously these devices ignored such interrupts while waiting on a READ. In direct mode, <CTRL-C> terminates a hung FIFO READ. Previously a FIFO device ignored a <CTRL-C> waiting on a READ. The direct mode behavior of the PIPE device remains the same, where a <CTRL-C> terminates PIPE subprocesses and the READ.

      The FIFO device correctly returns partial input for timed READs and sets status variables appropriately for fixed and UTF -8 mode READs. Previously a FIFO could hang and/or return partial data and/or not set status variables correctly for such READs.

      On z/OS, a readonly FIFO OPENs correctly and maintains $X properly. Previously on z/OS, readonly FIFO OPEN and $X misbehaved. [UNIX] (S9K02-002753)

    • READ from a SOCKET device provides improved protection against interrupts (for example, generated with MUPIP INTRPT). In prior releases, we had reports of segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Since FIS was unable to recreate these problems in the GT.M development environment, FIS cannot confirm whether they are entirely corrected. (S9K05-002770)

    • The jump optimizer in the GT.M compiler correctly optimizes the generated code in an obscure case. This issue started with V5.2-000 in certain 32-bit versions. While it is possible there are others, the only known condition to manifest symptoms is as follows: two nested argumentless DOs terminating on the same line where the inner DO preceded an argumentless FOR command on the same line containing no local variable references did not properly iterate. The only currently shipping version that showed this issue is x86 Linux, but 32-bit Solaris through V5.3-001A also might exhibit this problem. The workarounds for the identified symptom are to use an explicit QUIT or other code to avoid multiple argumentless DOs from terminating on the same line or ensure any line with a nested argumentless DO contains at least one local variable reference.[32-bit x86 Linux and 32-bit SPARC Solaris] (S9K07-002782).

    • GT.M local variable processing avoids occasional duplicate subscripts in local variable arrays. This addresses an interaction between GT.M and some versions of a C library (crtl) function. The code in question has been in GT.M for all versions and all platforms for a very long time (at least before V4.0-000). Even though this issue has only been reported on Linux x86 (32 bit) systems on V5.4-001, FIS believes that it is very hardware dependent and rare. It is also theoretically possible for this to manifest itself as a segmentation violation (SIG-11) on certain (usually older) x86 architecture CPUs, but FIS was was never able to replicate this in the GT.M development environment (S9K10-002786)

    • [V5.4-002A] M-profiling counts all types of FOR loops appropriately, and captures time consistently. When nesting levels exceed the facility's capacity to retain information, M-profiling stops detailed reporting and reports all subsequent time as a total. Previously FOR iterations were miscounted or not reported, and times could be very inaccurate; high levels of nesting could cause time capture to stop and restart with no accounting for the time between. M-profiling cannot and does not provide exact time information, but does provide a useful representation of where application code spends CPU cycles. Relative times reported by M-profiling should be meaningful. (S9L03-002804)

    • [V5.4-002A] The compiler gives FULLBOOLWARN warnings only in cases where the evaluation contains an AND (&) or an OR (!) with a $increment(), extrinsic function, or external call in other than the first element. In V5.4-002, it gave inappropriate warnings even in these cases where the side effect items are always evaluated. (S9L03-002807)

    • [V5.4-002B] $QLENGTH() and $QSUBSCRIPT() accept the non-standard (square-bracket) form of extended reference. Previously they only accepted the standard (up-bar) form. (S9L06-002813)

    • [V5.4-002B] GT.M handles job interrupts inside of a TP transaction more robustly. This fixes a regression introduced in V5.4-000, where a job interrupt that occurs inside a TP transaction that has not yet done any global reference but does some global reference inside the job interrupt code causing the first global reference after retunr from the job interrupt code to abnormally terminate with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) error. Note this abnormal termination could not affect database integrity. (S9L06-002816)

    • [V5.4-002B] $QSUBSCRIPT() returns a correct value when the selected subscript is exactly 0 (zero). Starting in V5.4-001, selecting a 0 subscript caused $QSUBSCRIPT() to return not only the 0 but all subsequent subscripts in the name. (S9L06-002820)

    • [V5.4-002B] $ZCONVERT() issues an ICUERROR error when ICU returns an inappropriate or unexpected error. Previously the process terminated with a GTMASSERT. [UNIX](S9L06-002821)

    • [V5.4-002B] VIEW "TRACE" works with triggers and call-ins. Previously, use of the VIEW "TRACE" facility with triggers or call-ins resulted in a GTMASSERT. [UNIX] (S9L06-002822)

    • ZWRITE accepts Intrinsic Special Variables (ISVs) as single arguments. This provides a way to easily expose non-graphic characters in individual ISVs. ISVs cannot be selected with the pattern matching and range syntax that ZWRITE accepts for global and local variables. As before, ZSHOW "I" provides a way to get all ISVs. In previous versions ZWRITE did not permit ISV arguments. (C9806-000511)

    • GT.M has a completely new implementation of local variables that scales much better for local variables with large numbers of nodes while preserving or even slightly improving upon the fast performance of local variables with small number of nodes that the previous implementation handled well. The new implementation outperforms global variables at all sizes tested, even local variables with hundreds of thousands of nodes. For local variables with more than a few thousand nodes, global variables outperformed the prior implementation. There is no functional difference.

      This refactoring effort also improved some other aspects of performance.

      The gtm_lvscale environment variable previously available to tune local variable structures is now ignored. You can safely let it remain in shell scripts that are designed to span GT.M versions with both local variable implementations.

      As part of the same effort, $QUERY() with standard NULL collation no longer skips descendants of an empty string subscript.

      Also as part of this effort, GT.M uniformly enforces the rule that a collation transform (or reverse transform) cannot modify an empty string ("NULL") subscript. In prior versions some, but not all operations enforced this rule, which applies to global variables as well as local variables. Note that transforms should not introduce empty string subscripts and GT.M does not currently protect against this. (C9905-001087)

    • An attempt to use a subscripted FOR control variable and calculate values assigned to it using expressions with side effects generates a FORCTRLINDX error. This construct presents some issues that can potentially cause incorrect results or segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Previous releases did not guard against this problem. Note GT.M does not detect the loss of a control variable specified by indirection and then destroyed within scope (by a KILL or NEW) and when it detects the loss of an unsubscripted indirect control variable does not report the name of that variable. FIS recommends against such usage as a source of program fragility; refer to C9L03-003392. (C9B03-001660)

    • GT.M provides an option to control evaluation of Boolean expressions (expressions evaluated as a logical TRUE or FALSE). By default, GT.M stops evaluating such expression as soon as it establishes a definitive result. For example, in this mode, neither 0&$$abc^def() or 1!$$abc^def() ever executes $$abc^def(). In the case of global references, such as 0&^a or 1!^a, GT.M correctly sets $Reference and the naked indicator without actually accessing the global variable.

      The settings may be altered with a VIEW command using an argument evaluating to (case-insensitive) "FULL_BOOLEAN" to select a evaluation order that evaluates expression atoms with short-circuit side effects prior to Boolean evaluation: "NOFULL_BOOLEAN" to select the traditional GT.M evaluation order which stops as soon as the result is known, and "FULL_BOOLWARN" which evaluates like "FULL_BOOLEAN" but also produces a BOOLSIDEFFECT warning when it encounters Boolean expressions that may induce side-effects; that is: expressions with side effects after the first Boolean operator - extrinsic functions, external calls and $INCREMENT(). The new gtm_boolean environment variable (UNIX) or GTM_BOOLEAN logical name (OpenVMS) provide initial values to control this behavior at process startup. If gtm_boolean is undefined or evaluates to an integer zero (0), the initial setting the default "NOFULL_BOOLEAN", if it evaluates to an integer one (1), the initial setting is "FULL_BOOLEAN" and if it evaluates to integer two (2) the initial setting is "FULL_BOOLWARN". Other numeric values are reserved for possible future controls - do not use them.

      These are compilation settings and the object code determines run-time execution independent of the current setting. As changing the compiler setting does not clear previously compiled and cached XECUTE arguments, changing the setting before an XECUTE may or may not produce a desired effect. "FULL_BOOLWARN" does not produce warnings on XECUTE arguments with potential side effects in Boolean evaluation.

      $VIEW("FULL_BOOLEAN") returns a string describing the current compiler setting.Note that while the FULL_BOOLEAN setting ensures that the side-effect expression atoms execute, it does not produce results that match full left-to-right evaluation in cases where the side-effect operation alters variables that appear before it in the Boolean expression. Therefore it's prudent to use the FULL_BOOLWARN setting to identify and evaluate and appropriately adjust the use of side-effect expression atoms in Boolean expressions.

      GT.M does not short-circuit evaluation if the first argument of a $INCREMENT() uses indirection. In prior releases, GT.M always compiled in "NOFULL_BOOLEAN" order, but exhibited inappropriate behavior when the first argument to $INCREMENT() used indirection, including spurious VAREXPECTED errors with no variable named by the error message, and incorrectly maintained $REFERENCE (and the naked indicator) when it skipped a $INCREMENT() both of whose arguments were global variables. If your application uses indirection for the first argument of $INCREMENT() in Boolean expressions, please analyze and test those instances thoroughly.

      Note that in the default short-circuit mode, global references within an extrinsic function are not reflected in the $REFERENCE of the caller, regardless of whether or not the extrinsic actually executes - this behavior is unchanged. (C9B04-001673)

    • Call ins offer a gtm_cip() interface, similar to gtm_ci() but using a handle, which improves performance on calls after the first one. gtm_cip() replaces the first argument of gtm_ci() with an argument of type struct ci_name_descriptor which contains the routine name and a handle to the call in function. GT.M populates the empty handle on the first call; the caller must not modify the handle (or bad things happen). Prior versions only offered the original gtm_ci() interface. This change also improved the performance of the original gtm_ci() interface. [UNIX] (C9D07-002340),

    • The gtm_exit call for GT.M call-ins cleans up any pending timers setup using the gt_timers interface and releases all associated memory. Previously, gtm_exit could leak a modest amount of memory used to track the timers. [UNIX](C9E12-002687)

    • $ZDATE() provides a date representation for day 0 (31-Dec-1840) and accepts two to six consecutive "Y" characters to indicate digits of year. Previously, $ZDATE() only accepted "YY" and "YEAR" to indicate two- and four-digit years respectively, and $ZDATE() of zero (0) produced an empty output. For example:

      GTM>write $zdate(123456789,"DAY MON DD, YYYYYY") 
 FRI MAR 17, 339854 
-GTM>

      (C9H02-002824)

    • [V5.4-002B] M-profiling more accurately reports time for large M programs with extensive routine invocations and tracks nested invocations as long as GT.M has available stack. In V5.4-002A, M-profiling over-reported time and, upon exceeding 1024 levels of nesting, aggregated all further time in one special entry. Note that the M-profiling changes in V5.4-002A were still more representative of relative time spent than in earlier versions. (C9L04-003409)

    • An "unlink all" capability allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref as the only current entry in the M virtual stack; GT.M preserves local variables and IO devices across the transition. ZGOTO to level 0 with an entryref specified (for example, ZGOTO 0:entryref) invokes this facility, which behaves as follows:

      • If the current invocation is a call-in, raise a ZGOCALLOUTIN error.

      • Stop M-Profiling (if active).

      • Unwind all routines in the M stack.

      • Unlink all routines, release allocated memory, and close any shared libraries containing GT.M generated object code.

      • Purge all cached objects (code generated for XECUTE and indirection).

      • Reset $ECODE, $REFERENCE, and $TEST to their initial (empty) values. Values of other intrinsic special variables are not affected.

      Previously, such usage terminated the process. [UNIX] (C9I09-003043)

    • [V5.4-002B] GT.M uniformly reports REQRUNDOWN for attempts to access an improperly shutdown database from the same node that last used it. Previously it sometimes inappropriately reported CLSTCONFLICT; CLSTCONFLICT indicates that the database was last used on, or is still in use on another node. [UNIX] (C9J03-003100)

    • [V5.4-002A] GTM properly resumes after a MUPIP INTRPT recognized during a ZSHOW or some forms of the FOR command. Previously, GTM was likely to resume, not where it was interrupted but at a previously executed location usually causing a GTMASSERT or SEG-V (UNIX SIG-11 or OpenVMS ACCVIO). (C9J06-003137)

    • The first line of an external call table is a path to the shared library containing the entry points for the external calls; GT.M permits that path to include environment variables, which are parsed and expanded with the same logic used for file names in segments in global directories. The environment variable names only include the "$"sign, "_", and alphanumerics. Note that GT.M parsing for environment variables does not handle curly-brace ({}) usage. For example, use $mysharedlibpath not ${mysharedlibpath}. [UNIX] (C9J09-003200)

    • GT.M correctly handles short (less than 3-byte) FIFO and PIPE READs in UTF-8 mode when they are not preceded by a UTF-8 Byte Order Mark (BOM). Previously a such READ could block if less than 3 bytes were available. [UNIX] (C9K05-003275)

    • GT.M no longer writes a <LF> to a PIPE device with unprocessed characters when the previous operation was a WRITE. Prior versions, performed this unnecessary flush of the PIPE. GT.M handles read x#n:0 correctly for the PIPE device. Previously, $TEST indicated a timeout even when READ returned the requested number of characters; and in some situations READ returned fewer characters than were available. [UNIX] (C9K08-003312)

    • GT.M again generates a GTM_FATAL_ERROR* ZSHOW type dump when it receives a fatal signal as it used to do except, by default, for segmentation violation (SIG-11). In V5.4-001, this diagnostic feature was inadvertently removed. [UNIX] (C9K08-003318)

    • GT.M loads ICU version 4.4 correctly when run in UTF-8 mode. Prior versions reported DLLNOOPEN or ICUSYMNOTFOUND error when trying to load ICU version 4.4 [Linux, Solaris, AIX, HP-UX IA64] (C9K09-003322)

    • GT.M reports the correct value for $ZREALSTOR. Since V5.3-001 the value was under-reported on some platforms potentially to the point of going negative and thus appearing as a very large value. [Linux, Tru64] (C9K10-003336)

    • $QSUBSCRIPT() handles multiple quotes mixed with non-graphic characters. In prior versions, this combination in a $QSUBSCRIPT() argument could give an incorrect result or fail with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K10-003338)

    • GT.M gives an UNDEF error when attempting to return an alias container where a subscript value is undefined. Previously, GT.M gave segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K12-003347)

    • GT.M handles the setup of the JOB command STARTUP script correctly - including issuing an error message if script fails. In V5.4-000[A] and V5.4-001 the argument might not be properly terminated and thus cause unpredictable results; also, the command did not report STARTUP script errors. GT.M issues an ERROR_SYSCALL message to the system log file if the JOB command PRIORITY variable fails. Previously, it made no report. [UNIX] (C9L02-003364)

    • [V5.4-002B] Device changes primarily for, but not restricted to, z/OS FIFO devices:

      • On z/OS, incorrect tagging can result when an OPEN command creates a new (not previously existing) fifo with the READONLY deviceparameter, as a GT.M READONLY attachment to a the fifo does no tagging, and relies on the first writer to tag the device. To ensure proper tagging under these circumstances, create the underlying fifo with the proper tagging before executing the GT.M OPEN command. Creation/tagging is unnecessary when the first writer attaches to the device before the reader performs the OPEN. Previously, a GT.M writer process which created and tagged a fifo could still result in the reader process getting incorrect tagging, resulting in inappropriate data conversion. [z/OS]

      • On z/OS, when a process performs an unrestricted (read/write) OPEN on a FIFO, or one with the WRITEONLY deviceparameter, it protects against uninitialized memory. Previously such a process could terminate with a segmentation violation (SIG-11). [z/OS]

      • On z/OS, when a process encounters an IO exception while performing an OPEN on a FIFO (other than with the READONLY deviceparameter), it removes both the GT.M device descriptor and the underlying OS fifo. Previously, such a process abandoned the OS fifo rather than removing it. [z/OS]

      • On UNIX, if a process attempts to READ from a sequential file, FIFO, or PIPE device opened with the WRITEONLY deviceparameter, it issues a GTM-E-DEVICEWRITEONLY error. Previously, such a READ caused a Bad file descriptor error. [UNIX]

      • On any platform when a process attempts to WRITE to a sequential file, FIFO or PIPE opened READONLY, it issues a GTM-E-DEVICEREADONLY. Previously, such a WRITE caused a GTM-E-RMSRDONLY. (C9L03-003382)

    • [V5.4-002A] ZBREAK manages the caching action of code objects more appropriately. Previously, substantial numbers of ZBREAK actions slowly choked off the indirection cache which slowed down all XECUTE and indirect processing. The nature of this issue typically kept it confined to lengthy debugging sessions, although it was possible to have a program demonstrate the problem by introducing lots of ZBREAK actions. The workaround was to restart the process. (C9L03-003390)

    • [V5.4-002B] FOR accepts a subscripted control variable in all circumstances. In addition it provides better detection, handling and reporting of cases where the control variable is KILL’d within the scope of the FOR. Note that NOUNDEF, which treats undefined values as the empty string, does not apply to missing FOR control variables when they are incremented, as that would tend to create apparently unintended indefinite loops. For example FOR A=1:1:10 KILL A gives an UNDEF error on the increment from 1 to 2 even in NOUNDEF mode. In V5.4-002 the most troublesome constructs gave a FORCTRLINDX error; prior to that they could produce unreliable results including segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). In addition, when the control variable disappeared in the scope of the FOR, the UNDEF message sometimes did not contain the name of the variable. (C9L03-003392)

    • [V5.4-002A] KILL * (KILL alias) works correctly and alias operations deal appropriately with alias containers at subscript levels greater than one. Previously, KILL * incorrectly removed even alias associations that were out of scope at the time of the command, possibly resulting in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) under some conditions. ZWRITE correctly reports subscripts of alias containers. Previously large numbers of alias containers could cause ZWRITE to misreport some subscripts even though the variables were correct. In addition, alias processing no longer skips alias containers at subscript depths greater than one. In V5.4-002, some alias processing skipped alias containers unless all their subscripted ancestors were also alias containers, which could cause associated variables to inappropriately disappear or processes to leak storage and possibly result in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9L04-003400)

    +GTM>

    (C9H02-002824)

  • [V5.4-002B] M-profiling more accurately reports time for large M programs with extensive routine invocations and tracks nested invocations as long as GT.M has available stack. In V5.4-002A, M-profiling over-reported time and, upon exceeding 1024 levels of nesting, aggregated all further time in one special entry. Note that the M-profiling changes in V5.4-002A were still more representative of relative time spent than in earlier versions. (C9L04-003409)

  • An "unlink all" capability allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref as the only current entry in the M virtual stack; GT.M preserves local variables and IO devices across the transition. ZGOTO to level 0 with an entryref specified (for example, ZGOTO 0:entryref) invokes this facility, which behaves as follows:

    • If the current invocation is a call-in, raise a ZGOCALLOUTIN error.

    • Stop M-Profiling (if active).

    • Unwind all routines in the M stack.

    • Unlink all routines, release allocated memory, and close any shared libraries containing GT.M generated object code.

    • Purge all cached objects (code generated for XECUTE and indirection).

    • Reset $ECODE, $REFERENCE, and $TEST to their initial (empty) values. Values of other intrinsic special variables are not affected.

    Previously, such usage terminated the process. [UNIX] (C9I09-003043)

  • [V5.4-002B] GT.M uniformly reports REQRUNDOWN for attempts to access an improperly shutdown database from the same node that last used it. Previously it sometimes inappropriately reported CLSTCONFLICT; CLSTCONFLICT indicates that the database was last used on, or is still in use on another node. [UNIX] (C9J03-003100)

  • [V5.4-002A] GTM properly resumes after a MUPIP INTRPT recognized during a ZSHOW or some forms of the FOR command. Previously, GTM was likely to resume, not where it was interrupted but at a previously executed location usually causing a GTMASSERT or SEG-V (UNIX SIG-11 or OpenVMS ACCVIO). (C9J06-003137)

  • The first line of an external call table is a path to the shared library containing the entry points for the external calls; GT.M permits that path to include environment variables, which are parsed and expanded with the same logic used for file names in segments in global directories. The environment variable names only include the "$"sign, "_", and alphanumerics. Note that GT.M parsing for environment variables does not handle curly-brace ({}) usage. For example, use $mysharedlibpath not ${mysharedlibpath}. [UNIX] (C9J09-003200)

  • GT.M correctly handles short (less than 3-byte) FIFO and PIPE READs in UTF-8 mode when they are not preceded by a UTF-8 Byte Order Mark (BOM). Previously a such READ could block if less than 3 bytes were available. [UNIX] (C9K05-003275)

  • GT.M no longer writes a <LF> to a PIPE device with unprocessed characters when the previous operation was a WRITE. Prior versions, performed this unnecessary flush of the PIPE. GT.M handles read x#n:0 correctly for the PIPE device. Previously, $TEST indicated a timeout even when READ returned the requested number of characters; and in some situations READ returned fewer characters than were available. [UNIX] (C9K08-003312)

  • GT.M again generates a GTM_FATAL_ERROR* ZSHOW type dump when it receives a fatal signal as it used to do except, by default, for segmentation violation (SIG-11). In V5.4-001, this diagnostic feature was inadvertently removed. [UNIX] (C9K08-003318)

  • GT.M loads ICU version 4.4 correctly when run in UTF-8 mode. Prior versions reported DLLNOOPEN or ICUSYMNOTFOUND error when trying to load ICU version 4.4 [Linux, Solaris, AIX, HP-UX IA64] (C9K09-003322)

  • GT.M reports the correct value for $ZREALSTOR. Since V5.3-001 the value was under-reported on some platforms potentially to the point of going negative and thus appearing as a very large value. [Linux, Tru64] (C9K10-003336)

  • $QSUBSCRIPT() handles multiple quotes mixed with non-graphic characters. In prior versions, this combination in a $QSUBSCRIPT() argument could give an incorrect result or fail with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K10-003338)

  • GT.M gives an UNDEF error when attempting to return an alias container where a subscript value is undefined. Previously, GT.M gave segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K12-003347)

  • GT.M handles the setup of the JOB command STARTUP script correctly - including issuing an error message if script fails. In V5.4-000[A] and V5.4-001 the argument might not be properly terminated and thus cause unpredictable results; also, the command did not report STARTUP script errors. GT.M issues an ERROR_SYSCALL message to the system log file if the JOB command PRIORITY variable fails. Previously, it made no report. [UNIX] (C9L02-003364)

  • [V5.4-002B] Device changes primarily for, but not restricted to, z/OS FIFO devices:

    • On z/OS, incorrect tagging can result when an OPEN command creates a new (not previously existing) fifo with the READONLY deviceparameter, as a GT.M READONLY attachment to a the fifo does no tagging, and relies on the first writer to tag the device. To ensure proper tagging under these circumstances, create the underlying fifo with the proper tagging before executing the GT.M OPEN command. Creation/tagging is unnecessary when the first writer attaches to the device before the reader performs the OPEN. Previously, a GT.M writer process which created and tagged a fifo could still result in the reader process getting incorrect tagging, resulting in inappropriate data conversion. [z/OS]

    • On z/OS, when a process performs an unrestricted (read/write) OPEN on a FIFO, or one with the WRITEONLY deviceparameter, it protects against uninitialized memory. Previously such a process could terminate with a segmentation violation (SIG-11). [z/OS]

    • On z/OS, when a process encounters an IO exception while performing an OPEN on a FIFO (other than with the READONLY deviceparameter), it removes both the GT.M device descriptor and the underlying OS fifo. Previously, such a process abandoned the OS fifo rather than removing it. [z/OS]

    • On UNIX, if a process attempts to READ from a sequential file, FIFO, or PIPE device opened with the WRITEONLY deviceparameter, it issues a GTM-E-DEVICEWRITEONLY error. Previously, such a READ caused a Bad file descriptor error. [UNIX]

    • On any platform when a process attempts to WRITE to a sequential file, FIFO or PIPE opened READONLY, it issues a GTM-E-DEVICEREADONLY. Previously, such a WRITE caused a GTM-E-RMSRDONLY. (C9L03-003382)

  • [V5.4-002A] ZBREAK manages the caching action of code objects more appropriately. Previously, substantial numbers of ZBREAK actions slowly choked off the indirection cache which slowed down all XECUTE and indirect processing. The nature of this issue typically kept it confined to lengthy debugging sessions, although it was possible to have a program demonstrate the problem by introducing lots of ZBREAK actions. The workaround was to restart the process. (C9L03-003390)

  • [V5.4-002B] FOR accepts a subscripted control variable in all circumstances. In addition it provides better detection, handling and reporting of cases where the control variable is KILL’d within the scope of the FOR. Note that NOUNDEF, which treats undefined values as the empty string, does not apply to missing FOR control variables when they are incremented, as that would tend to create apparently unintended indefinite loops. For example FOR A=1:1:10 KILL A gives an UNDEF error on the increment from 1 to 2 even in NOUNDEF mode. In V5.4-002 the most troublesome constructs gave a FORCTRLINDX error; prior to that they could produce unreliable results including segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). In addition, when the control variable disappeared in the scope of the FOR, the UNDEF message sometimes did not contain the name of the variable. (C9L03-003392)

  • [V5.4-002A] KILL * (KILL alias) works correctly and alias operations deal appropriately with alias containers at subscript levels greater than one. Previously, KILL * incorrectly removed even alias associations that were out of scope at the time of the command, possibly resulting in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) under some conditions. ZWRITE correctly reports subscripts of alias containers. Previously large numbers of alias containers could cause ZWRITE to misreport some subscripts even though the variables were correct. In addition, alias processing no longer skips alias containers at subscript depths greater than one. In V5.4-002, some alias processing skipped alias containers unless all their subscripted ancestors were also alias containers, which could cause associated variables to inappropriately disappear or processes to leak storage and possibly result in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9L04-003400)

    • Utilities-MUPIP

    • MUPIP BACKUP -REPLACE applies to both specified files and files in specified directories. A destination specification that causes the same backup command to reuse a destination file for more than one source generates an error regardless of whether or not you specify -REPLACE. Note that -REPLACE only applies to -DATABASE backups. In prior versions -REPLACE only applied when the command specified target directories, but not files. [UNIX] (S9E02-002420)

    • [V5.4-002B] MUPIP RUNDOWN ensures correct relationship among database ID, database Name and Shared Memory before running down database files. RUNDOWN sends the IDs of any removed IPC resource (shared memory and/or semaphore) to the operator log. Previously, under certain unusual operational circumstances, MUPIP RUNDOWN could take a suboptimal or unintended action and display any removed IPC resource IDs on only the terminal issuing the command. The table below summarizes the modified cases. [UNIX] (C9K06-003280) (S9C01-002024)

      Case

      		 @@ -1223,10 +1223,10 @@ GTM>

      (C9H02-002824)

      		•

      Oldest shared memory rundown"File is in use by another process" message for one or more other segments

      -

    • For performance reasons, MUPIP RECOVER and MUPIP ROLLBACK never use the synchronous / direct I/O option when opening journal files for recovery or rollback, whether or not the SYNC_IO option of MUPIP SET -JOURNAL was used to create them. In prior versions, RECOVER and ROLLBACK used the same options as the run-time system, even though synchronous / direct I/O is not optimal for these MUPIP operations. [UNIX] (S9E04-002445)

    • Source and Receiver Server processes include additional information (host error number and error string) in their respective log files when they encounter connection reset errors while sending or receiving messages. Prior versions did not include this information and hence made it difficult to determine the cause of the connection reset. (S9I04-002680)

    • [V5.4-002B] MUPIP RECOVER -BACKWARD checks the database transaction number against the journal file transaction number and if they don’t align, issues an error. Previously, RECOVER -BACKWARD, did not detect such a mismatch between database and journal file, which could have allowed an operator error to cause a flawed recovery leaving integrity errors. (S9I05-002683) (C9L01-003351)

    • [V5.4-002B] A new environment variable called gtm_jnl_release_timeout allows you to specify the number of seconds that a replicating Source Server waits when there is no activity on an open journal file before closing it. The default wait period is 300 seconds. If gtm_jnl_release_timeout specifies 0, the Source Server keeps the current journal files open until shutdown. The maximum value for gtm_jnl_release_timeout is 2147483 seconds. Previously, the Source Server kept the current journal files open until its shutdown. [UNIX] (S9I12-002716)

    • [V5.4-002A] The startup of a replicating instance deals appropriately with a sequence where the Receiver Server is killed and restarted with Helper Processes and then the Update Process is killed. Previously, the Receiver Server hung trying to ensure proper shutdown of the Update Process started before its own start. Note that such a condition is more likely to occur in a test environment simulating system crashes than in a real environment - in a real environment, if a system crashes, all processes and all resources go down, a condition from which GT.M recovers well. [UNIX] (S9L04-002809)

    • [V5.4-002A] When a MUPIP REPLICATE -INSTANCE_CREATE command renames an existing file due to a name conflict, it prints a FILERENAME message acknowledging the operation. Additionally, a -NOREPLACE qualifier on the command prevents the renaming of a potentially existing file. Previously, MUPIP REPLICATE did not offer the -NOREPLACE option and did the rename without a warning message. [UNIX] (S9I05-002990)

    • MUPIP JOURNAL issues the JNLTPNEST error message as a Warning because MUPIP processes the associated condition appropriately. In previous versions JNLTPNEST was an Error, which was slightly misleading. (C9D11-002456)

    • MUPIP REPLIC -SOURCE -SHOW -JNLPOOL displays a maximum of 16 printable characters for the "Instance File Created Nodename" field of the replication instance file header. Prior versions, displayed a maximum of 15 printable characters. [UNIX] (C9K03-003241)

    • MUPIP RUNDOWN removes orphaned semaphores even if no shared memory exists. In prior versions, RUNDOWN did not remove abandoned GT.M database semaphores when they had no corresponding shared memory. [UNIX] (C9K07-003297)

    • MUPIP INTEG -SUBSCRIPT and -BLOCK preserve the integrity of the database in case it has a mix of V4 and V5 format GDS blocks. In prior V5 versions, this used to silently introduce a DBBTUWRNG integ error in an otherwise clean database. (C9K07-003303)

    • MUPIP SET JOURNAL and MUPIP BACKUP, as part of turning journaling ON in a database, create journal files that are in sync with the database. In previous versions, it was possible in rare cases for these to create a journal file whose transaction number did not match with the database. This used to result in JNLFILOPN and JNLTRANSLSS errors when opening this journal file which caused GT.M to make one more (extra) journal switch to fix this situation. (C9K08-003304)

    • MUPIP JOURNAL RECOVER and ROLLBACK defer MUPIP STOP request-handling during several brief sections of the code to maintain the integrity of the database state after an interrupted RECOVER/ROLLBACK process. Previously, a MUPIP STOP command received by a MUPIP JOURNAL RECOVER/ROLLBACK process within a certain small window could leave journaling/replication disabled. (C9K08-003305)

    • [V5.4-002B] MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -EXTRACT -FORWARD report a JNLFILEDUP error when the command specifies duplicate journal files in forward recovery. Previously, they incorrectly reported JNLTNOUTOFSEQ or JNLBADRECFMT errors while processing the journal files instead of detecting the duplicate input and refusing to proceed.MUPIP JOURNAL -INTERACTIVE requires a non-empty response but defaults to a NO on an EOF. Previously, it defaulted an empty response to YES and prompted again after an EOF. Because the -INTERACTIVE option seems seldom used, we felt it prudent to adopt a more conservative approach; you can always rerun the RECOVER and answer YES if you desire a different outcome. In addition, -INTERACTIVE only re-prints the continue prompt upon wrong user input and only waits for a single response. Previously, it re-printed the prompt at a fixed interval even if there was no user input and might have ignored a response, sometimes requiring the user to answer twice.Utility programs looking for an interactive YES/NO including LKE, MUPIP ENDIANCVT, and MUPIP JOURNAL report any error reading from user input and consider it as a NO. Previously, MUPIP JOURNAL would re-print the prompt and LKE and MUPIP ENDIANCVT would assume a default NO without reporting the issue. [UNIX] (C9K08-003315)

    • MUPIP REPLICATE -INSTANCE_CREATE defers renaming the current replication instance file until after it verifies that it has sufficient information to create a new one. In prior versions, if the replicating instance name was not provided (either in the command line or through the environment variable gtm_repl_instname), this command renamed the existing instance file and issued a REPLINSTNMUNDEF error without creating a new replacement instance file. [UNIX] (C9K09-003320)

    • MUPIP INTEG reports misaligned database file as DBMISALIGN. Previously, this error was not differentiated from DBTOTBLK. (C9K11-003341)

    • MUPIP JOURNAL ROLLBACK recovers the database correctly even if it has NULL records (a special type of journal record). These records are never written into the journal file when executing normal application logic, but are potentially inserted into the replication stream by schema change filters for rolling upgrades that involve changes to the application schema or internally by GT.M's replication mechanism when replicating between different GT.M versions (for example, from a version with trigger support to one without). Previously, the presence of such records could cause rollback to create more unreplicated (lost) transactions than necessary which also meant rolling the database further back in time than necessary. (C9L02-003362)

    • [V5.4-002A] MUPIP JOURNAL -ROLLBACK consumes less memory when checking transaction consistency. Previously, the memory consumption during ROLLBACK was nearly eight times higher. (C9L02-003366)

    • [V5.4-002A] MUPIP BACKUP allows an argument in the destination list to be as long as the maximum path the platform can support. Previously, MUPIP BACKUP silently truncated arguments longer than 255 characters to that length. [UNIX except z/OS] (C9L03-003386)

    • [V5.4-002A] The Source Server stops with a REPLNOMULTILINETRG error when it is replicating to an instance that does not support multi-line triggers and it needs to send a trigger definition update that includes a multi-line XECUTE code string too large to store in a single record. This fixes an issue resulting from the introduction of multi-line triggers in V5.4-002, in which the Source Server sent the trigger update, the replicating instance accepted the update, but would never XECUTE it because the XECUTE code string appeared empty. [UNIX] (C9L04-003399)

    • [V5.4-002B] The first database access after a MUPIP RESTORE of an encrypted data database leaves the encryption properly set up. Previously, that first database access after a RESTORE cleared the encryption state, even when the database was encrypted. The workaround was to correct the encryption setting with DSE. [UNIX] (C9L04-003406)

    • [V5.4-002B] The replication log files record information about orphaned semaphores (GT.M generated) and shared memory resulting from an error in the shutdown of the Receiver Server or Update Process. In prior versions, GT.M did not record this information in the replication log files. [UNIX] (C9L06-003434)

    - Utilities-Other Than MUPIP

    • GDE appropriately handles adjacent maximum length (31 character) names. In Previous versions, such names mapped correctly originally, but either gave an error when attempting to use GDE on the global directory or could disappear on reprocessing the directory. (C9E11-002658)

    • The GT.M configure installation script no longer creates arch.gtc in the parent of the installation directory. Previously, this script erroneously created this file. [UNIX] (S9K08-002783)

    • GDE provides a -COMMAND qualifier for the SHOW command with an optional -FILE= qualifier. This displays commands that recreate the current global directory state. -FILE= optionally specifies a file to hold the commands. In addition, SHOW -TEMPLATE gives an encryption indication for BG except on OpenVMS where it does not apply. Prior versions did not offer SHOW -COMMAND or display encryption status for BG templates. (C9H08-002889)

    • If the environment variable $LC_CTYPE is not specified when the $gtm_chset environment variable specifies that GT.M run in UTF-8 mode, the gtmprofile script defaults $LC_CTYPE to the first UTF-8 locale. Previously, any upper-case U, T, and F characters in that first UTF-8 locale name were incorrectly converted to lower case. [UNIX] (C9K07-003299)

    • The automatic execution of GDE in the gtmprofile script to create a default global directory if one does not exist includes an stty sane command to turn on echoing of characters in the terminal session. Previously, it left the terminal in a state where it did not echo characters. Note that this provides a workaround to an issue in GDE/GT.M - in our judgment at the current time this is a better option than attacking the root cause, given the minor nature of the issue and the simplicity of the workaround. [UNIX] (C9K08-003310)

    • The GT.CM OMI server gives an appropriate error message for an over-sized value of gtm_dist and exits. This also changes the GT.CM log file destination to match that of the rest of GT.M. Previously such an operation error caused a stack overflow and core file, and error messages went to the user.error log while messages from other GT.M components go to user.info. [UNIX] (C9K08-003311)

    • GDE SHOW includes reserved bytes value (RES) for templates. In prior releases SHOW did not display this information. (C9K08-003317)

    • The configure installation script correctly modifies the gpgagent.tab file to point to the GT.M encryption library in the installation directory. Previously, it failed to do this on AIX and HP-UX Itanium. This may have resulted in the pinentry program not working correctly on AIX/HP-UX Itanium servers using GPG2 with the reference implementation encryption plugin. [AIX, HP-UX Itanium] (C9K09-003323)

    • The configure installation script is executable and explicitly executes /bin/sh. Previously, the execute bit was not set and a shell had to be explicitly specified. The revised script also supports changing the installation group without also having to restrict access to this group. Previously, the installation group could not be changed without restricting access to this group. The installation script correctly handles invalid ICU version entry lower than 3.6. Previously, this resulted in shell script errors. The installation script correctly handles restricted group for UTF-8 mode. Previously, it did not allow the owner of the installation to execute in UTF-8 mode if not a member of the restricted group. [UNIX] (C9K09-003324)

    • [V5.4-002A] GT.M utilities defer signal handling during process start-up. Previously, there was a small window where an error during process start-up could cause a deadlock on resources used to log the error message. [UNIX] (C9K11-003342)

    • If bash is available, the add_db_key.sh script properly handles Unicode characters in directory paths. Previously, on Ubuntu 6.10 and above the default sh is dash instead of bash. Dash does not properly handle Unicode characters in directory paths, for example, during indirection. Because the add_db_key.sh script runs with the default shell, it failed. [UNIX] (C9L01-003356)

    • GTMSECSHR properly reports an error if it is unable to change directory to its temporary directory. Previously, GTMSECSHR did not report this error. Note: It would be highly unusual for GTMSECSHR not be able to change directories - perhaps indicative of something amiss in the system or OS configuration. [UNIX] (C9L02-003365)

    • The new gtminstall script is an experimental facility to simplify GT.M installation. It attempts to provide reasonable defaults while allowing considerable customization using command line switches. When unpacked and executed as root without any parameters, that is, just ./gtminstall, from within the directory where the GT.M distribution is unpacked it installs GT.M with M mode support only in the directory /usr/lib/fis-gtm/version_platform, for example, /usr/lib/fis-gtm/V5.4-002_x86_64.

      Separated from GT.M as a stand-alone script, it attempts to determine the latest / current production version for its hardware platform, and to download that version and install it. gtminstall --help lists the options.

      Example usage scenarios include:

      sudo gtminstall # installs latest version in M mode only
+

  • For performance reasons, MUPIP RECOVER and MUPIP ROLLBACK never use the synchronous / direct I/O option when opening journal files for recovery or rollback, whether or not the SYNC_IO option of MUPIP SET -JOURNAL was used to create them. In prior versions, RECOVER and ROLLBACK used the same options as the run-time system, even though synchronous / direct I/O is not optimal for these MUPIP operations. [UNIX] (S9E04-002445)

  • Source and Receiver Server processes include additional information (host error number and error string) in their respective log files when they encounter connection reset errors while sending or receiving messages. Prior versions did not include this information and hence made it difficult to determine the cause of the connection reset. (S9I04-002680)

  • [V5.4-002B] MUPIP RECOVER -BACKWARD checks the database transaction number against the journal file transaction number and if they don’t align, issues an error. Previously, RECOVER -BACKWARD, did not detect such a mismatch between database and journal file, which could have allowed an operator error to cause a flawed recovery leaving integrity errors. (S9I05-002683) (C9L01-003351)

  • [V5.4-002B] A new environment variable called gtm_jnl_release_timeout allows you to specify the number of seconds that a replicating Source Server waits when there is no activity on an open journal file before closing it. The default wait period is 300 seconds. If gtm_jnl_release_timeout specifies 0, the Source Server keeps the current journal files open until shutdown. The maximum value for gtm_jnl_release_timeout is 2147483 seconds. Previously, the Source Server kept the current journal files open until its shutdown. [UNIX] (S9I12-002716)

  • [V5.4-002A] The startup of a replicating instance deals appropriately with a sequence where the Receiver Server is killed and restarted with Helper Processes and then the Update Process is killed. Previously, the Receiver Server hung trying to ensure proper shutdown of the Update Process started before its own start. Note that such a condition is more likely to occur in a test environment simulating system crashes than in a real environment - in a real environment, if a system crashes, all processes and all resources go down, a condition from which GT.M recovers well. [UNIX] (S9L04-002809)

  • [V5.4-002A] When a MUPIP REPLICATE -INSTANCE_CREATE command renames an existing file due to a name conflict, it prints a FILERENAME message acknowledging the operation. Additionally, a -NOREPLACE qualifier on the command prevents the renaming of a potentially existing file. Previously, MUPIP REPLICATE did not offer the -NOREPLACE option and did the rename without a warning message. [UNIX] (S9I05-002990)

  • MUPIP JOURNAL issues the JNLTPNEST error message as a Warning because MUPIP processes the associated condition appropriately. In previous versions JNLTPNEST was an Error, which was slightly misleading. (C9D11-002456)

  • MUPIP REPLIC -SOURCE -SHOW -JNLPOOL displays a maximum of 16 printable characters for the "Instance File Created Nodename" field of the replication instance file header. Prior versions, displayed a maximum of 15 printable characters. [UNIX] (C9K03-003241)

  • MUPIP RUNDOWN removes orphaned semaphores even if no shared memory exists. In prior versions, RUNDOWN did not remove abandoned GT.M database semaphores when they had no corresponding shared memory. [UNIX] (C9K07-003297)

  • MUPIP INTEG -SUBSCRIPT and -BLOCK preserve the integrity of the database in case it has a mix of V4 and V5 format GDS blocks. In prior V5 versions, this used to silently introduce a DBBTUWRNG integ error in an otherwise clean database. (C9K07-003303)

  • MUPIP SET JOURNAL and MUPIP BACKUP, as part of turning journaling ON in a database, create journal files that are in sync with the database. In previous versions, it was possible in rare cases for these to create a journal file whose transaction number did not match with the database. This used to result in JNLFILOPN and JNLTRANSLSS errors when opening this journal file which caused GT.M to make one more (extra) journal switch to fix this situation. (C9K08-003304)

  • MUPIP JOURNAL RECOVER and ROLLBACK defer MUPIP STOP request-handling during several brief sections of the code to maintain the integrity of the database state after an interrupted RECOVER/ROLLBACK process. Previously, a MUPIP STOP command received by a MUPIP JOURNAL RECOVER/ROLLBACK process within a certain small window could leave journaling/replication disabled. (C9K08-003305)

  • [V5.4-002B] MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -EXTRACT -FORWARD report a JNLFILEDUP error when the command specifies duplicate journal files in forward recovery. Previously, they incorrectly reported JNLTNOUTOFSEQ or JNLBADRECFMT errors while processing the journal files instead of detecting the duplicate input and refusing to proceed.MUPIP JOURNAL -INTERACTIVE requires a non-empty response but defaults to a NO on an EOF. Previously, it defaulted an empty response to YES and prompted again after an EOF. Because the -INTERACTIVE option seems seldom used, we felt it prudent to adopt a more conservative approach; you can always rerun the RECOVER and answer YES if you desire a different outcome. In addition, -INTERACTIVE only re-prints the continue prompt upon wrong user input and only waits for a single response. Previously, it re-printed the prompt at a fixed interval even if there was no user input and might have ignored a response, sometimes requiring the user to answer twice.Utility programs looking for an interactive YES/NO including LKE, MUPIP ENDIANCVT, and MUPIP JOURNAL report any error reading from user input and consider it as a NO. Previously, MUPIP JOURNAL would re-print the prompt and LKE and MUPIP ENDIANCVT would assume a default NO without reporting the issue. [UNIX] (C9K08-003315)

  • MUPIP REPLICATE -INSTANCE_CREATE defers renaming the current replication instance file until after it verifies that it has sufficient information to create a new one. In prior versions, if the replicating instance name was not provided (either in the command line or through the environment variable gtm_repl_instname), this command renamed the existing instance file and issued a REPLINSTNMUNDEF error without creating a new replacement instance file. [UNIX] (C9K09-003320)

  • MUPIP INTEG reports misaligned database file as DBMISALIGN. Previously, this error was not differentiated from DBTOTBLK. (C9K11-003341)

  • MUPIP JOURNAL ROLLBACK recovers the database correctly even if it has NULL records (a special type of journal record). These records are never written into the journal file when executing normal application logic, but are potentially inserted into the replication stream by schema change filters for rolling upgrades that involve changes to the application schema or internally by GT.M's replication mechanism when replicating between different GT.M versions (for example, from a version with trigger support to one without). Previously, the presence of such records could cause rollback to create more unreplicated (lost) transactions than necessary which also meant rolling the database further back in time than necessary. (C9L02-003362)

  • [V5.4-002A] MUPIP JOURNAL -ROLLBACK consumes less memory when checking transaction consistency. Previously, the memory consumption during ROLLBACK was nearly eight times higher. (C9L02-003366)

  • [V5.4-002A] MUPIP BACKUP allows an argument in the destination list to be as long as the maximum path the platform can support. Previously, MUPIP BACKUP silently truncated arguments longer than 255 characters to that length. [UNIX except z/OS] (C9L03-003386)

  • [V5.4-002A] The Source Server stops with a REPLNOMULTILINETRG error when it is replicating to an instance that does not support multi-line triggers and it needs to send a trigger definition update that includes a multi-line XECUTE code string too large to store in a single record. This fixes an issue resulting from the introduction of multi-line triggers in V5.4-002, in which the Source Server sent the trigger update, the replicating instance accepted the update, but would never XECUTE it because the XECUTE code string appeared empty. [UNIX] (C9L04-003399)

  • [V5.4-002B] The first database access after a MUPIP RESTORE of an encrypted data database leaves the encryption properly set up. Previously, that first database access after a RESTORE cleared the encryption state, even when the database was encrypted. The workaround was to correct the encryption setting with DSE. [UNIX] (C9L04-003406)

  • [V5.4-002B] The replication log files record information about orphaned semaphores (GT.M generated) and shared memory resulting from an error in the shutdown of the Receiver Server or Update Process. In prior versions, GT.M did not record this information in the replication log files. [UNIX] (C9L06-003434)

    • + Utilities-Other Than MUPIP

    • GDE appropriately handles adjacent maximum length (31 character) names. In Previous versions, such names mapped correctly originally, but either gave an error when attempting to use GDE on the global directory or could disappear on reprocessing the directory. (C9E11-002658)

    • The GT.M configure installation script no longer creates arch.gtc in the parent of the installation directory. Previously, this script erroneously created this file. [UNIX] (S9K08-002783)

    • GDE provides a -COMMAND qualifier for the SHOW command with an optional -FILE= qualifier. This displays commands that recreate the current global directory state. -FILE= optionally specifies a file to hold the commands. In addition, SHOW -TEMPLATE gives an encryption indication for BG except on OpenVMS where it does not apply. Prior versions did not offer SHOW -COMMAND or display encryption status for BG templates. (C9H08-002889)

    • If the environment variable $LC_CTYPE is not specified when the $gtm_chset environment variable specifies that GT.M run in UTF-8 mode, the gtmprofile script defaults $LC_CTYPE to the first UTF-8 locale. Previously, any upper-case U, T, and F characters in that first UTF-8 locale name were incorrectly converted to lower case. [UNIX] (C9K07-003299)

    • The automatic execution of GDE in the gtmprofile script to create a default global directory if one does not exist includes an stty sane command to turn on echoing of characters in the terminal session. Previously, it left the terminal in a state where it did not echo characters. Note that this provides a workaround to an issue in GDE/GT.M - in our judgment at the current time this is a better option than attacking the root cause, given the minor nature of the issue and the simplicity of the workaround. [UNIX] (C9K08-003310)

    • The GT.CM OMI server gives an appropriate error message for an over-sized value of gtm_dist and exits. This also changes the GT.CM log file destination to match that of the rest of GT.M. Previously such an operation error caused a stack overflow and core file, and error messages went to the user.error log while messages from other GT.M components go to user.info. [UNIX] (C9K08-003311)

    • GDE SHOW includes reserved bytes value (RES) for templates. In prior releases SHOW did not display this information. (C9K08-003317)

    • The configure installation script correctly modifies the gpgagent.tab file to point to the GT.M encryption library in the installation directory. Previously, it failed to do this on AIX and HP-UX Itanium. This may have resulted in the pinentry program not working correctly on AIX/HP-UX Itanium servers using GPG2 with the reference implementation encryption plugin. [AIX, HP-UX Itanium] (C9K09-003323)

    • The configure installation script is executable and explicitly executes /bin/sh. Previously, the execute bit was not set and a shell had to be explicitly specified. The revised script also supports changing the installation group without also having to restrict access to this group. Previously, the installation group could not be changed without restricting access to this group. The installation script correctly handles invalid ICU version entry lower than 3.6. Previously, this resulted in shell script errors. The installation script correctly handles restricted group for UTF-8 mode. Previously, it did not allow the owner of the installation to execute in UTF-8 mode if not a member of the restricted group. [UNIX] (C9K09-003324)

    • [V5.4-002A] GT.M utilities defer signal handling during process start-up. Previously, there was a small window where an error during process start-up could cause a deadlock on resources used to log the error message. [UNIX] (C9K11-003342)

    • If bash is available, the add_db_key.sh script properly handles Unicode characters in directory paths. Previously, on Ubuntu 6.10 and above the default sh is dash instead of bash. Dash does not properly handle Unicode characters in directory paths, for example, during indirection. Because the add_db_key.sh script runs with the default shell, it failed. [UNIX] (C9L01-003356)

    • GTMSECSHR properly reports an error if it is unable to change directory to its temporary directory. Previously, GTMSECSHR did not report this error. Note: It would be highly unusual for GTMSECSHR not be able to change directories - perhaps indicative of something amiss in the system or OS configuration. [UNIX] (C9L02-003365)

    • The new gtminstall script is an experimental facility to simplify GT.M installation. It attempts to provide reasonable defaults while allowing considerable customization using command line switches. When unpacked and executed as root without any parameters, that is, just ./gtminstall, from within the directory where the GT.M distribution is unpacked it installs GT.M with M mode support only in the directory /usr/lib/fis-gtm/version_platform, for example, /usr/lib/fis-gtm/V5.4-002_x86_64.

      Separated from GT.M as a stand-alone script, it attempts to determine the latest / current production version for its hardware platform, and to download that version and install it. gtminstall --help lists the options.

      Example usage scenarios include:

      sudo gtminstall # installs latest version in M mode only
 sudo gtminstall --utf8 default # install latest version with UTF-8 mode support
-sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a local directory

      [UNIX](C9L03-003371)

    • [V5.4-002A] DSE CHANGE -BLOCK -TN correctly handles updates to encrypted databases without journaling. In V5.4-002, using DSE on such a database to set the transaction number for a block to a value that is less than the current database transaction number caused segmentation violation (SIG-11). [UNIX] (C9L03-003391)

    • [V5.4-002B] The gtminstall script deals with releases with letter suffixes. Previously the script would fail with an expression error. [UNIX] (C9L05-003410)

    • [V5.4-002B] Command line processing in utilities (like DSE, LKE, MUPIP) handles empty user responses robustly. Previously, in rare cases, an empty response (a newline) could result in segmentation violation (SIG-11) [UNIX] (C9L05-003411)

    +sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a local directory

    [UNIX](C9L03-003371)

  • [V5.4-002A] DSE CHANGE -BLOCK -TN correctly handles updates to encrypted databases without journaling. In V5.4-002, using DSE on such a database to set the transaction number for a block to a value that is less than the current database transaction number caused segmentation violation (SIG-11). [UNIX] (C9L03-003391)

  • [V5.4-002B] The gtminstall script deals with releases with letter suffixes. Previously the script would fail with an expression error. [UNIX] (C9L05-003410)

  • [V5.4-002B] Command line processing in utilities (like DSE, LKE, MUPIP) handles empty user responses robustly. Previously, in rare cases, an empty response (a newline) could result in segmentation violation (SIG-11) [UNIX] (C9L05-003411)

    • Error Messages

    The new and revised error message(s) for V5.4-002 are as follows:

    BOOLSIDEFFECT

    BOOLSIDEFFECT, Extrinsic ($$), External call ($&) or $INCREMENT() with potential side effects in Boolean expression

    Compile Time Warning: This optional message, accompanied by a line and column pointing to the issue, indicates a Boolean expression that contains a side effect in a term other than its first. By default, GT.M may skip evaluating such terms.

    Action: Revise the code to your standards and use the VIEW (arguments [NO]FULL_BOOLEAN or FULLBOOL_WARN) command and / or the environment variable (gtm_boolean) to select the appropriate setting for GT.M handling of this construct.

    DBBADUPGRDSTATEM

    DBBADUPGRDSTATE, Correcting conflicting values for fields describing database version upgrade state in the file header for region rrrr (ffff) - make fresh backups with new journal files immediately.

    Run Time Warning: This warning message in the operator log indicates region rrrr (file ffff) had an out-of-design combination of database upgrade conditions, which may have caused defective journal files and -online BACKUPs. GT.M automatically corrects this condition, but you should investigate the possible causes for such file header damage.

    Action: Make fresh backups with new journal files immediately.

    DBMISALIGN

    DBMISALIGN, Database file xxxx has yyyy blocks which does not match alignment rules. Reconstruct the database from a backup or extend it by at least zzzz blocks.

    MUPIP Error: This is an auxiliary message, and is preceded by a primary message.

    Action: Follow the primary message description and action as specified in this manual.

    DBSHMNAMEDIFF [V5.4-002B]

    Database file ffff points to shared memory mmmm which points to a different database file

    Runtime Error: Database access gives this error, if the database is copied or moved without properly closing it. This error indicates that database ffff and shared memory mmmmm do not correspond to each other.

    Action: Perform MUPIP RUNDOWN on the database.

    DEVICEWRITEONLY [V5.4-002B]

    Cannot read from a write-only device

    Run-time error: The application made an attempt to READ from a device in a WRITEONLY state, typically due to the OPEN command specifications

    Action: Check for logic errors and revise the code.

    @@ -1238,9 +1238,9 @@ sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a loc JNLTPNEST

    JNLTPNEST, Mupip journal command found nested TP transactions for journal file jjjj at offset oooo at transaction number nnnn

    MUPIP Warning: MUPIP JOURNAL -RECOVER or ROLLBACK encountered a TSTART record for transaction nnnn at offset oooo in journal file jjjj while already processing an uncommitted transaction. Since the run-time system should never produce this situation, the journal file is suspect. MUPIP discards the in-progress transaction and proceeds.

    Action: Extract the journal file(s) and use the context from the message to find the transactions in question and adjust for any lost or tangled transaction(s).

    REPLJNLCNFLCT

    REPLJNLCNFLCT, Journaling cannot be turned nnnn on database file ffff as the replication state is rrrr and must also be turned nnnn in the same command

    MUPIP Warning: This message indicates that the requested journaling state (nnnn) and current replication state (rrrr, which is either "ON" or "[WAS_ON]" ) do not match and the command must explicitly specify an outcome such that they do match. WAS_ON is a state where journaling has been lost but replication has been able to continue by running from the journal pool without needing the lost journal file(s) - the MUPIP SET command needs to explicitly turn this state back to ON.

    Action: Issue one or more commands that leave journaling and replication either both ON or both OFF.

    REPLNOXENDIAN

    REPLNOXENDIAN, SSSS side is running on a GT.M version that does not support cross-endian replication. Upgrade the SSSS side to at least V5.3-003 to support cross-endian replication. Cannot continue.

    MUPIP Error : The originating or the replicating instance in a cross-endian replication environment issue this error when a replication startup detects that the other side is running on a GT.M version without needed cross-endian support.

    Action : Upgrade the instance for which the error was reported to a version with support for cross-endian replication.

    - REPLNOMULTILINETRG [V5.4-002A]

    REPLNOMULTILINETRG, Sequence number ssss contains a trigger definition too large for transmission to the current replicating instance, which does not support multi-line triggers - stopping replication.

    Run Time Error: If you are upgrading an originating instance before a replicating instance (FIS recommends upgrading the replicating instance first), you must not use any new functionality in the originating instance until all the replicating instances have been upgraded so they can also support that functionality. Starting with V5.4-002, trigger definitions code for XECUTE can have multiple lines while prior to that it had to fit on a single line. The Update Process produces this error and stops the Source Server when an older replicating instance cannot handle a multi-line trigger XECUTE code that is too large to store in a single record.

    Action: To continue replication, either upgrade the replicating instance to V5.4-002 or higher or change the application to eliminate multi-line triggers that are too large to store in a single record.

    + REPLNOMULTILINETRG [V5.4-002A]

    REPLNOMULTILINETRG, Sequence number ssss contains a trigger definition too large for transmission to the current replicating instance, which does not support multi-line triggers - stopping replication.

    Run Time Error: If you are upgrading an originating instance before a replicating instance (FIS recommends upgrading the replicating instance first), you must not use any new functionality in the originating instance until all the replicating instances have been upgraded so they can also support that functionality. Starting with V5.4-002, trigger definitions code for XECUTE can have multiple lines while prior to that it had to fit on a single line. The Update Process produces this error and stops the Source Server when an older replicating instance cannot handle a multi-line trigger XECUTE code that is too large to store in a single record.

    Action: To continue replication, either upgrade the replicating instance to V5.4-002 or higher or change the application to eliminate multi-line triggers that are too large to store in a single record.

    REPLXENDIANFAIL

    REPLXENDIANFAIL, SSSS side encountered error while doing endian conversion at journal sequence number JJJJ

    Error: The originating or the replicating instance in a cross-endian replication environment report this error whenever they detect that the endian conversion failed.

    Action: Restart replication - if the transmission caused the problem, it’s probably intermittent. Perform a MUPIP JOURNAL -EXTRACT -DETAIL on the journal files and search for the sequence number JJJJ to look for anything different about that journal record. If the report is on the secondary, take a fresh backup on the originating instance requesting new journal files, refresh the replicating instance and restart replication.

    - SECNODZTRIGINTP

    SECNODZTRIGINTP, Sequence number ssss contains $ZTRIGGER() updates made inside a transaction which the current replicator does not support. The replicator must be upgraded to at least V5.4-002 to support this type of transaction. Cannot continue

    MUPIP Error: The originating instance encountered a $ZTRIGGER() function within a transaction with sequence number ssss. However, the replicating instance is running a pre-V5.4-002 version which cannot handle $ZTRIGGER() within a transaction.

    Action: Upgrade the replicating instance to V5.4-002 or later. Alternatively adjust the application code to avoid using $ZTRIGGER() within a transaction.

    In [V5.4-002A], changed the message summary of SECNODZTRIGINTP to:

    + SECNODZTRIGINTP

    SECNODZTRIGINTP, Sequence number ssss contains $ZTRIGGER() updates made inside a transaction which the current replicator does not support. The replicator must be upgraded to at least V5.4-002 to support this type of transaction. Cannot continue

    MUPIP Error: The originating instance encountered a $ZTRIGGER() function within a transaction with sequence number ssss. However, the replicating instance is running a pre-V5.4-002 version which cannot handle $ZTRIGGER() within a transaction.

    Action: Upgrade the replicating instance to V5.4-002 or later. Alternatively adjust the application code to avoid using $ZTRIGGER() within a transaction.

    In [V5.4-002A], changed the message summary of SECNODZTRIGINTP to:

    SETINSETTRIGONLY

    SETINSETTRIGONLY, ISV iiii can only be modified in a 'SET' type trigger

    Run Time Error: Code invoked for a trigger other than SET (such as KILL or ZTRIGGER) attempted to modify Intrinsic Special Variable iiii, which applies only within a SET trigger context.

    Action: Review the trigger definition and correct the types or the code to avoid the issue.

    SHMREMOVED [V5.4-002B]

    Shared Memory id mmmm removed from the system

    MUPIP information: MUPIP RUNDOWN removed shared memory segment mmmm with a GT.M signature because it was not currently in use.

    Action: No action required.

    SSFILOPERR

    SSFILOPERR, Error while doing oooo operation on file ffff

    Mupip Error: This operator log message indicates operation oooo on snapshot file ffff failed. Note in certain timing situations this action might be reported to the operator log after the snapshot consuming process (say MUPIP INTEG) has finished with the snapshot file, in which case it's harmless. If the consuming process issues a REGSSFAIL error, then it was definitely prevented from completing its tack because of the SSFILOPERR.

    Action: Analyze the operation and the file characteristics and take appropriate action to clear the problem.

    TPLOCKRESTMAX

    TPLOCKRESTMAX, Transaction restarts due to unavailability of locks not allowed in a final TP retry more than nnnn times

    Run Time Error: This indicated a timed LOCK within a transaction was consistently unavailable. In order to prevent the process from waiting for the LOCK while holding a database resource (critical section) the transaction has restarted nnnn times without success. This error limits the possibilities for this issue cascading into a live-lock (consuming resources trying to do something that is "not happening").

    Action: Analyze the locking protocol for issues of dead lock or unexpected LOCK durations and rework appropriately. Note that FIS recommends against using LOCKs within transactions, as GT.M protects the transaction integrity independent of LOCK protocols. If you wish to impose a conventional locking strategy for a transaction, place the LOCK and unlock around (outside) the transaction. While it is possible to use a LOCK within a transaction for signaling, that technique is typically problematic as it violates transactional Isolation and should likely be restricted to testing.

    diff --git a/articles/GTM_V5_4_000A_Release_Notes.html b/articles/GTM_V5_4_000A_Release_Notes.html index 70574fe..5136d47 100644 --- a/articles/GTM_V5_4_000A_Release_Notes.html +++ b/articles/GTM_V5_4_000A_Release_Notes.html @@ -1,5 +1,5 @@ - Technical Bulletin - GT.M V5.4-000/V5.4-000A Release Notes

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

    Copyright A(C) 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.Ma?c 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.


    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity.  Refer to the GT.M Triggers Technical Bulletin for details.


      Please note: FIS considers the implementation of triggers in V5.4-000/V5.4-000A to be robust, and entirely appropriate for development and testing short of production deployment.  With the next release of GT.M, they will have had gone through many more cycles of automated regression testing under a broader range of conditions, and will be considered production grade at that time.  If you are an FIS customer and are ready to deploy in production an application that uses GT.M triggers, please contact your FIS account manager about the timing and availability of a GT.M release in which triggers will be considered production grade.  Depending on circumstances, we may even decide then that the implementation of triggers in V5.4-000/V5.4-000AA is robust enough for production.  Except for the triggers functionality, everything else in V5.4-000/V5.4-000A is considered production grade.


    • MUPIP INTEG can now check a database for structural integrity while applications continue to operate.  In prior releases of GT.M, MUPIP INTEG would freeze updates.  Online operation is now the default for databases that contain no version 4 format database blocks.

    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.

     

     

    Return to Table of Contents

    Platforms

    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 Programmera??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 componentsa?? 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 a??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 a??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 a??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 a??UPGRADE in either of the following situations:
     
    • A database was created by a V5 MUPIP CREATE
    • A database has previously been completely processed by a MUPIP REORG a??UPGRADE from V5.3-003 or later
     
    If you have already run the MUPIP REORG a??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:
     
    • Run the MUPIP REORG a??UPGRADE command again
    • Run the DSE CHANGE a??FULLY_UPGRADED=1 command to stop the warnings
       
      Caution: Do not run the DSE CHANGE -FILEHEADER a??FULLY_UPGRADED=1 command unless you are absolutely certain you have previously successfully run to completion MUPIP REORG a??UPGRADE from V5.3-003 or later. Using this command when inappropriately may lead to database integrity issues.

     

    For additional upgrade considerations, see "Database Compatibility Notes".  
     
    Database Compatibility Notes
    • Changes to the database file header may occur in any release.  GT.M automatically upgrades database file headers as needed.  Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.
    • Databases created with V5.3-004 and later can grow to a maximum size of 224M (234,881,024) blocks.  This means, for example, that with an 8KB block size, the maximum database file size is 1,792GB (this is the size of a single global variable; a database consists of any number of global variables).  A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128M to 224M blocks.
    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128M (134,217,728) blocks.  Until and unless a database created with V5.3-004 (or later), or created in V5.0-000 through V5.3-003, exceeds the 128M block limit of earlier V5 GT.M releases, it can be accessed by releases V5.0-000 through V5.3-003. 

    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:


    • On AIX systems, if you upgrade from 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later
    • On Linux systems, if you upgrade from a 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later or from a 64-bit release to a newer 32-bit release
    • On Sun SPARC Solaris, if you upgrade from 32-bit pre-V5.3-003 to 64-bit V5.3-003

     

    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: 

     
    • Create a fresh backup of your database.
    • Generate new journal files (without back-links).

     

    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 a??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 a??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.

     

     
    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M.  GT.M itself does not have any knowledge of specific terminal control characteristics.  Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal.  You may need to add new terminfo entries depending on their specific platform and implementation.  The terminal (emulator) vendor may also be able to help.
    • GT.M uses the following terminfo capabilities.  The full variable name is followed by the capname in parenthesis:
      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

     

    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:
     

    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

    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity. Refer to the GT.M Triggers Technical Bulletin for details.


      A MUPIP RECOVER which stops due to an error before making any database modifications also leaves the file header unchanged. Previously, MUPIP RECOVER marked the database header with the "corrupt" flag and did not clear it for that case. (S9I08-002695)

    • GT.M no longer issues JNLCNTRL errors when VIEW "JNLWAIT" commands are executed after a journal file switch. Previously, in rare cases, GT.M incorrectly issued a JNLCNTRL error. (S9I09-002699)

    • GDE now preserves the mapping of multiple lexically adjacent maximum length global names. In prior versions, GDE created such ranges correctly but lost track of them when reloading the global directory for examination or a subsequent update. The workaround was to always reestablish such ranges after invoking GDE. This issue was reported from a pre-V5 environment where the maximum name length was eight characters rather than the current 31 characters. There is less chance of encountering this issue on versions V5.0-000 and later. (S9K02-002754) V5.4-000A

    • GT.M now ensures $INCREMENT() produces a numeric result even when the first argument is an undefined global variable and the second argument is a string containing non-numeric characters. Prior versions returned a string in this condition. If the first argument was a local variable, this worked properly in earlier versions. Note while the case in question is unusual enough to be unlikely, any code that relied on the prior behavior needs updating. (C9F07-002746)

    • GDE now ignores blank lines in command files. After being interrupted while processing a command file, it also properly closes the file and appropriately resumes the next action. In prior versions, GDE treated blank lines as errors and could fail with a GDECHECK error if a command file was interrupted at certain points with <CTRL-C>. (C9H10-002920) V5.4-000A

    • A GT.M process now reports a more helpful ERR_REQRUNDOWN error when it fails to attach to a shared memory segment (because of a prior improper shutdown e.g. kill -9). On detecting such a situation, prior versions instead reported the less helpful ERR_DBFILERR. [UNIX] (C9J08-003178)

    • As long as the operating system permits the access, GT.M now allows access to database files and journals in cases where the system has no user or group information available for the file. Such an unusual situation can arise, for example, when the user and group are provided via NIS, but if NIS is not currently operational the owner and group cannot be determined; or perhaps a user id is deleted while the GT.M process is active. V5.3-004[A] issued a signal-11 in such a case. [UNIX] (C9J09-003198)

    • GT.M now properly releases memory in response to a gtmcrypt_close() function call. Previously, depending upon how quickly memory was re-allocated, a gtmcrypt_close() function call could result in a signal 11 causing GT.M to abnormally terminate. [Unix] (C9J09-003190)

    • GT.M now maintains database integrity even when multiple GT.M processes simultaneously attempt to create the same global variable. This fixes a regression in GT.M V5.3-000 (also present in V5.3-004A and introduced as part of the fixes to C9H09-002901) where, in such situations, it was possible under rare circumstances for the GT.M process to cause database damage (for example, DBINVGBL or DBKEYORD errors). Note that this was an issue only for non-TP updates, that is those which were not surrounded by a TSTART/TCOMMIT. (C9J10-003202)

    • Using "" as the last subscript in a global argument to $ORDER(gvn,-1) or $ZPREVIOUS(gvn) now maintains $REFERENCE correctly. This fixes a regression introduced in GT.M version V5.3-004 (and present in V5.3-004A) as part of the fix for C9E10-002648. (C9J10-003203)

    • GT.M now deals correctly with a set of rare cases where it could inappropriately interpret negative numbers in database block control structures as large positive numbers. Previous versions might terminate with memory access violations, or get into indefinite or inappropriately long loops. This was discovered in testing DSE against a database with intentionally inflicted damage, which we expect is characteristic of the unusual conditions that might expose this issue. (C9J10-003208)

    • GT.M now correctly implements an optimization (that avoids unnecessary global variable tree traversals) for TP transactions. This fixes a regression introduced in GT.M V5.3-004 (and present in V5.3-004A) which in rare cases could cause an incorrect TPFAIL error to be issued (note: this regression did not affect the integrity of the database). (C9J11-003214)
    • GT.M now correctly handles a case where a TP transaction updates the same block, holding the same global multiple times, along with updates of blocks of other globals, and some other process, most likely MUPIP REORG, replaces the block in question with an almost identically configured block from another global in the transaction between the first and second updates of the original block. In previous versions, it was possible for this unusual combination of conditions to cause an incorrect update. The likelihood of this issue increased due to a recent change (C9905-001119) in GT.M V5.3-004 which enabled a global reference caching optimization for TP. (C9K01-003220)


    Return to Table of Contents

    M-Other Than Database Access

    • GT.M now issues a LOCKSPACEFULL error to the application and the operator log when the environment attempts more concurrent M LOCKs than the configured LOCK_SPACE for the region can support. Previously under these conditions, GT.M gave a fatal GTMASSERT error. (S9C11-002251)

    • GT.M now reports an error if the first argument of a two argument $GET() is defined and the second is an undefined local variable. Prior versions returned the value of the first argument and ignored the error mandated by the standard. If the second argument was a global variable, this worked properly in earlier versions. Note that any code that relies on the prior behavior needs updating. (S9D08-002354)

    • GT.M now reports UNDEF errors when it encounters an undefined variable specified for a local variable subscript as it already does for a global variable and as defined in the language standard. In prior versions, KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY() ignored these errors. Under NOUNDEF operation this change has no user impact. Note: code that relied on the earlier non-standard behavior may now give errors and require revision.

      GT.M now supports VIEW "NEVERLVNULLSUBS" to issue the LVNULLSUBS error for any inappropriate use of empty string subscripts in local arrays.  The [new] gtm_lvnullsubs UNIX environment variable can have the values 0 - equivalent to VIEW "NOLVNULLSUBS", 1  (the default) - equivalent to VIEW "LVNULLSUBS" or  2 - equivalent to VIEW "NEVERLVNULLSUBS". In VMS, the initial state of this characteristic is controlled by the GTM$DEFAULTS file. An empty string as the last subscript in $ORDER() and $QUERY() has the semantic significance of requesting the next lexical item and is not subject to NULLSUBS errors. $VIEW("LVNULLSUBS") returns the corresponding numeric value. In prior versions, GT.M only supported NOLVNULLSUBS, which reported the LVNULLSUBS error for SET commands that would have instantiated a prohibited local array subscript, but not for KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY().  $VIEW("LVNULLSUBS") returned 0 for NOLVNULLSUBS and 1 for LVNULLSUBS. Note that code that expected $VIEW("LVNULLSUBS") to provide a truth value must be revised. Empty string subscript checking for global variables is controlled by a database region characteristic that was already comprehensive and is not affected by this change. Note that programs using empty subscripts for references where those references cannot possibly exist are wasting computer resources, so FIS recommends using LVNULLSUBS or NEVERLVNULLSUBS for local variables and NULLSUBS options ALWAYS or NEVER for global variables. (S9D10-002376) V5.4-000A

    • If the OPEN or USE for a SOCKET device does not specify a MOREREADTIME parameter, any READ uses an initial 200msec internal timeout to minimize CPU load. Subsequent attempts to acquire more characters to fulfill the same READ use a 10msec internal timeout. When a MOREREADTIME parameter specifies a value, READ uses that value exclusively. Previously READ used a default of 10msec when no MOREREADTIME parameter was specified and consequently could consume considerable CPU cycles, especially on a lightly loaded system. If your application currently uses the MOREREADTIME parameter, FIS suggest that you consider whether this new behavior provides better performance and/or reduces CPU usage and allows you to avoid specifying MOREREADTIME. (S9J07-002732)

    • The distribution tar file now provides all files owned by the innocuous user:group ids 40535:40535, with no executable or writable files. With the exception of AIX, no directories have write permissions. On AIX, unpacking the distribution file no longer requires root permissions. In prior versions, the configure script adjusted the authorizations, but the distribution had various settings, and, on AIX, required root access to unpack the distribution. [UNIX] (S9J07-002737)

    • GT.M now handles the OPEN of a PIPE device better in certain situations. In prior versions, specifying various device parameters such as ESCAPE for the $PRINCIPAL device when it was a terminal could result in delays or other problems. [UNIX] (S9J11-002749)

    • GT.M now ensures a proper value for $QUIT on x86 and x86-64 GNU/Linux. In V5.4-000 under certain circumstances, it could return an inappropriate result. [x86-64 Linux, x86 Linux] (S9K02-002755) V5.4-000A

    • On compiling an M program, GT.M now omits reports showing the point in the line of code that caused the warning or error for lines longer than 1023 characters; it still reports the line number and column number. In prior versions, attempts to report such long lines could overrun an internal buffer and cause the process to hang or fail. (S9K02-002756) V5.4-000A

    • GT.M now correctly detects an attempt to SET a variable with an "NULL" subscript resulting from an undefined variable when using a VIEW "NOLVNULLSUBS", "NOUNDEF" combination. In versions starting with V5.3-001, the changes associated with C9B03-001664 exposed a latent problem such that GT.M did not detect a SET using an undefined local variable as a subscript as an error, but instead could use an indeterminate value for the subscript. (S9K03-002759) V5.4-000A
    • GT.M now uses buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting. While the performance difference of the buffered read approach is significant, most applications limit their use of the affected features so the overall effect may not be noticeable. Previously, GT.M used unbuffered reads which used many system calls. [UNIX] (S9K03-002761) V5.4-000A

    • The TRUNCATE parameter on USE for sequential file devices now works correctly for Linux. In prior versions, USE could truncate at the wrong position. [Linux] (C9E02-002513)

    • The GT.M SOCKET device behavior has improved in a number of ways.

      SOCKET CONNECT operations now respond to MUPIP INTRPT; in prior versions they did not.

      If the command does not specify a timeout, a SOCKET OPEN now waits for the connection to complete or an interrupting event that terminates the attempt. After an interrupt that does not terminate the connection attempt, such as the default value of $ZINTERRUPT ("IF $ZJOBEXAM()"), the process resumes the wait when the XECUTE of the $ZINTERRUPT completes. Previously, an untimed SOCKET OPEN <device>:CONNECT would make a single attempt to connect and return whether or not it was successful, as if it had a timeout of 0.

      SOCKET CONNECT status values EINPROGRESS, EWOULDBLOCK and, on some platforms, EALREADY now wait for the connection to complete or for the specified timeout to expire.  Previously, GT.M treated these conditions as errors.

      If IOERROR="TRAP" is specified on a SOCKET OPEN or USE, it now invokes any active EXCEPTION, $ETRAP, or $ZTRAP if an error occurs on a CONNECT.  The above status values as well as ECONNREFUSED and ETIMEDOUT are not considered as errors.  Previously, status values other than ECONNREFUSED or ETIMEDOUT would always be treated as errors regardless of the IOERROR value. (C9D07-002356, C9H06-002868)

    • GT.M now allows only a single set of gtm_init/gtm_exit per process and any attempt to call gtm_init/gtm_ci after a gtm_exit returns the code associated with the CALLINAFTERXIT error. Earlier GT.M versions also did not support invoking gtm_init or gtm_ci after a gtm_exit but did not enforce the restriction.[UNIX] (C9H07-002875)

    • GT.M now preserves all terminal input when handling an INTRPT in UTF-8 mode. In addition, INTRPT handling now preserves and restores the INSERT terminal characteristic. In prior versions, there was a slight chance a few characters of UTF-8 mode terminal input for either a READ or Direct Mode input could be lost and/or that the INSERT setting would revert to the default after the INTRPT event. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9H10-002913)
    • GT.M handling of INTRPT processing now protects the values of $ECODE and $STACK() at the time it recognizes the INTRPT. Prior versions allowed the code invoked by the $ZINTERUPT vector to modify those values, probably unintentionally, which could lead to a confused error processing state after completion of the $ZINTERUPT action. (C9J04-003108)

    • READ from a sequential disk file in UTF-8 mode read buffers the file reads for higher throughput. In prior versions, single character reads limited performance. [UNIX] (C9J04-003118)

    • The UNIX installation script for GT.M now sets the executable bits for files such as mumps and mupip only after a successful installation. Previously, the executable bits for these files were sometimes set after an unsuccessful installation. [UNIX] (C9J06-003140)

    • Both gtmsecshr and GT.M now prevent buffer overflow by checking the length of the gtm_tmp environment variable based on the system-specific sun_path length. In recent and properly patched versions of GT.M this was done only in gtmsecshr_wrapper. [UNIX] (C9J06-003145)

    • ZSHOW and ZWRITE now display information about alias variables with no associated data provided at least two of the joined variables are selected by the command argument. In prior releases these commands displayed alias containers with no data, but not alias variables with no data. When an alias exists with no data for the command to display, GT.M holds the variable so that it can become the right-hand side of a proper SET * command. However, if the command selection criteria excludes any other alias, GT.M has insufficient information to form a valid SET * argument and does not display that alias. Alias container variables always have a default value (the empty string), so they are handled differently and display as they did before. (C9J07-003148)

    • GT.M now handles very large object files correctly on z/OS. V5.3-003[A] produced invalid object files if the generated code exceeded 32KB. [z/OS] (C9J08-003170)

    • In UTF8 mode, when the minor version is not specified in the environment variable gtm_icu_version, e.g. 3 instead of 3.6, GT.M issues an ICUSYMNOTFOUND error. Previous versions of GT.M used to issue the ICUVERLT36 error even when the major version specified was greater than or equal to 4. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9J08-003174)

    • ^%XCMD is a utility program that XECUTEs input from the shell command line and returns any error status (truncated to a single byte on UNIX) generated by that code. For example in UNIX: mumps -run %XCMD 'write "hello world",!' would produce "hello world" (C9J08-003179)

    • GT.M now correctly handles the CLOSE of a PIPE device whose STDERR device is the current device.  Prior versions issued a segmentation violation in such a case. [UNIX] (C9J09-003188)

    • The file gtmprofile, which sets up a default environment for GT.M has been completely revamped to make it more robust and to make the out-of-box GT.M experience friendlier.  gtmprofile now sets up default values for more environment variables, creates a default global directory if one does not exist and a default database with before image journaling, if one does not exist.  The new executable shell script gtm uses gtmprofile and automatically recovers the database on startup.  gtm also deletes prior generation journal and temporary files older than the number of days specified by the environment variable gtm_retention.  A new file gdedefaults specifies default values for global directories.  The new gtmprofile script is also idempotent (can be successfully rerun after an abnormal termination), unlike its predecessor.  FIS recommends that system administrators review the gtmprofile and gdedefaults files after installing GT.M, and customize them as needed.  The previous gtmprofile file remains available as gtmprofile_preV54000 - if you want to retain the previous behavior, simply replace gtmprofile with gtmprofile_preV54000.  Note that at this time, the file gtmcshrc has not been similarly revamped for csh/tcsh users (the gtm script does not depend on the underlying shell).  [UNIX] (C9J09-003197)  

    • The distribution tar file may now be installed if there is no "bin" user and/or group defined.  The operator may now enter an alternate user and/or group to own the installation and may also restrict access to this group.  Previously the installation failed if the default bin user were specified and did not exist, or if the bin group did not exist - even if another restricted group was chosen. [UNIX] (C9J09-003201)

    • The new $gtm_stdxkill/GTM_STDXKILL environment/logical variable (UNIX/VMS) which if set to "TRUE", 1, or "YES" enables the standard-compliant behavior to kill local variables in the exclusion list if they had an alias that was not in the exclusion list. GT.M default behavior for exclusive kills thus reverts to its previous behavior, not compliant with the standard, where aliases and pass-by-reference variables specified in an exlusive kill are NOT killed even if their aliases are not specified in the exclusion list. In GT.M V5.3-004 (C9B09-001754), this behavior was changed to be compliant with the standard as part of the alias variables enhancement.  Please note that the default value is FALSE, so you must explicitly ask for standard-compliant behavior. (C9J11-003211)

    • String pool expansion is now more responsive to the rate at which the application requires space for local variables. This enhancement significantly improves the performance of applications that ramp up to atypically large string pool requirements (in the hundreds of thousands of local variable nodes), while preserving the more parsimonious string pool usage of typical applications. (C9J12-003215)

    • GT.M now allows an unsubscripted local variable, alias or alias container to be returned using the QUIT * syntax to a function invocation initiated using a SET *lvn=$$func() syntax. The SET * associates the target "lvn" local variable to the data space specified by the returning QUIT *. Previously GT.M only allowed alias information to be returned using the M pass-by-reference mechanism or by an alias in scope in both the caller and called routines. Additionally, the $QUIT ISV now returns the value "11" to indicate the current routine was invoked by a SET * and is required to return an alias using a QUIT * syntax. Failure to provide a QUIT * return as requested by the invocation produces an ALIASEXPECTED error. Providing a QUIT * return when not requested by the invocation produces a QUITALSINV error. (C9J12-003217)

    • UNIX editions will not report a value for $STORAGE larger than (2GB - 1)  [2,147,483,647], even if more is available. Previous versions could fail with SEG-V (SIG-11) errors while attempting to report $STORAGE values. [UNIX] (C9K01-003225). 

    • The configure installation script now assigns the correct permissions to the gtmsecshr wrapper for a non-restricted group installation.  It also creates symbolic links required for GTM and GDE help in utf-8 mode.  Previously, the setuid bit was not set for the gtmsecshr wrapper on some platforms and [z]help would fail in utf-8 mode.[UNIX] (C9K02-002758) V5.4-000A

     

    Return to Table of Contents

    Utilities-MUPIP

    • MUPIP and GT.M now clean up temporary snapshot files from INTEG under a wider variety of conditions. In V5.4-000, stopping the INTEG with a <CTRL-C> or a signal could leave the snapshot file orphaned. [UNIX] (S9K02-002757) V5.4-000A

    • MUPIP INTEG -REGION now supports the -ONLINE qualifier. This allows checking database structural integrity to run concurrently with database updates. Previously, INTEG froze updates on each region while checking it. Online integ is not supported with the -FILE qualifier. The -NOONLINE qualifier indicates that the database should be frozen during the MUPIP INTEG operation.

      The -ONLINE qualifier is now the default for MUPIP INTEG, except for databases containing V4 blocks, for which the default is -NOONLINE. Note that databases containing V4 blocks should exist only in databases that are in the process of being migrated from V4 to V5; please complete your migration to the V5 format before using MUPIP INTEG -ONLINE.

      The environment variable GTM_BAKTMPDIR (unlike most GT.M environment variables, this is upper case; it is the same directory used for MUPIP BACKUP -ONLINE) can be used to indicate a directory where MUPIP should place the snapshot files (used by online integ). If GTM_BAKTMPDIR does not exist, MUPIP places the snapshot files in the current directory at the time you issue the INTEG command.

      As it checks each database file, MUPIP INTEG -ONLINE creates a sparse file of the same size as the database.  As each GT.M process updates the database, it places a copy of the old block in the sparse file before updating the database.  For any database blocks with a newer transaction number than the start of the INTEG, MUPIP uses the copy in the sparse file.  Thus, analogous with MUPIP BACKUP -ONLINE, INTEG reports on the state of the database as of when it starts, not as of when it completes.  Note: a command such as ls -l command shows sparse files at their full size, but does not show actual disk usage. Use a command such as du -sh to see actual disk usage.

      Temporary directory security settings must allow write access by the the MUPIP process and read access by all processes updating the database. MUPIP creates the temporary file with the same access as the database file so processes updating the database can write to the temporary file. If the database is encrypted, the updating processes write encrypted blocks to the snapshot file and the MUPIP INTEG process must start with access to appropriate key information as it does even -NOONLINE.

      Only one online integ can be active per database region. If an online integ is already active, a subsequent one issues an error and immediately terminates. If an online integ does not successfully complete, GT.M cleans it up in one of the following ways:

    •  
      • A subsequent online integ detects that an earlier one did not successfully complete and releases the resources held by the prior online integ before proceeding.
      • If a MUPIP STOP was issued to the online integ process, the process cleans up any resources it held. Note: since the process was stopped the results of the integ may not be valid.
      • A subsequent MUPIP RUNDOWN ensures the release of resources held by prior unsuccessful online integs for the specified regions.
      • For every 64K transactions after the online integ initiation, online integ health GT.M checks for improperly abandoned online integs and releases resources held by any it finds.
       
      Because the online integ (now the default for most integs) does not freeze database updates, it cannot safely correct errors in the "blocks to upgrade" and "free blocks" fields in the file header, while MUPIP INTEG -NOONLINE can correct these fields.
        
      The -ONLINE qualifier is incompatible with the -TN_RESET qualifier. In any case, there should be no need to use -TN_RESET on a GT.M V5 database. [UNIX] (C9902-000839)

    • MUPIP INTEG -TN_RESET now resets block transaction numbers and backup event recorded transaction numbers to (one) 1, and the current transaction number to two (2) which makes the backup event recorded transaction numbers more meaningful and useful. It also issues an advisory message to perform a backup. Previously the backup event recorded transaction numbers were not maintained by -TN_RESET, which meant they held inappropriate information. Note that there should never be a need for a -TN_RESET on a datbase with only V5 blocks, even when cleaning up after a runaway process. (C9B12-001842)

    • GT.M now provides a new monitoring facility for processes holding a resource for an unexpected amount of time. This facility runs a shell command or a script pointed to by the new environment variable gtm_procstuckexe when any of the following conditions occur:  


      1. An explicit MUPIP FREEZE or an implicit freeze, such as BACKUP, INTEG -ONLINE, and so on, after a one minute wait on a region. 
      2. MUPIP actions find kill_in_prog (KILLs in progress) to be non-zero after a one minute wait on a region. Note that GT.M now internally maintains a list of PIDs (up to a maximum of 8 PIDs) currently doing a KILL operation.  
      3. The BUFOWNERSTUCK, INTERLOCK_FAIL, JNLPROCSTUCK, SHUTDOWN, WRITERSTUCK and MAXJNLQIOLOCKWAIT operator messages are being logged.


      Typically, for the shell script or command pointed to by gtm_procstuckexec, you would write corrective and preventive actions or obtain the stack trace of the troublesome processes (using their PIDs). GT.M passes arguments to the shell command / script in the order specified below:


      1. condition is the name of the condition. For example, BUFOWNERSTUCK, INTERLOCK_FAIL, and so on.
      2. waiting_pid is the PID of the process reporting the condition. 
      3. blocking_pid is the PID of the process holding a resource. 
      4. count is the number of times the script has been invoked for the current condition (1 for the first occurrence).


      Each invocation generates an operator log message and if the invocation fails an error message to the operator log. The shell script should start with a line beginning with #! that designates the shell. 


      Note: Make sure you have sufficient space and permissions to run the shell command / script.


      Prior versions wait for the condition to clear and in most cases send messages to the operator log. [UNIX] [C9D08-002390]

    • MUPIP now verifies that the byte ordering (endian-ness) of a journal file matches the byte ordering of the instance on which it is running and issues an error in case of a mismatch. In prior versions, such a case of operational cross-threading caused MUPIP to fail with various complaints about the journal file format or even a memory access violation (SIG-11 or ACCVIO). (C9J04-003110)

    • The replication source server now handles database files that are in WAS_ON replication state (and in turn a journaling state of OFF) in a safe manner. If it cannot find the journal records in the journal pool, it reads as many journal records as possible from the journal file chain and when it reaches the point where journaling got turned OFF, it periodically displays a REPL_WARN message until journaling gets turned back ON and then correctly issues a NOPREVLINK error. At all points, it behaves as a read-only process as far as journaling is concerned and never switches journal files. In previous versions of GT.M, it was possible for the source server to incorrectly attempt a switch of journal files in such WAS_ON regions eventually terminating with many types of errors (JNLFILOPN etc.). (C9J07-003156) V5.4-000A

    • The messages produced by a replicating instance when the originating instance encounters a REPLINSTNOHIST error now read:

      Originating instance encountered a REPLINSTNOHIST error. JNL_SEQNO of this replicating instance precedes the current history in the originating instance file. uuuu exiting.

      Where uuuu is either a rollback or the receiver server. [UNIX] (C9J08-003166)

    • By default, a Source Server now waits for a maximum of one and a half minute per region to shutdown. In prior versions, the maximum wait period for Source Server shutdown was approximately four minutes irrespective of the number of regions. (C9J09-003195).

    • MUPIP BACKUP -REPLINSTANCE now ensures its backup of the replication instance file is in sync with all databases backed up as part of the same command. This fixes a regression introduced in GT.M V5.3-000 (and present in V5.3-004A) that could in rare cases cause REPLINSTDBMATCH error when attempting to use the backed-up instance file because it held an incorrect sequence number for a database file. A workaround for this is to recreate the instance file, as the backed up databases are correct. (C9K01-003222)[UNIX]

    • GT.M now correctly handles an unusual set of circumstances that can occur if MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE are running concurrently with M transaction processing. In V5.4-000, these unusual circumstances could cause a SIG-11. [UNIX] (C9K02-003239) V5.4-000A

     

    Return to Table of Contents

    Utilities-Other Than MUPIP

    • DSE, LKE, and MUPIP now handle unusually long command input lines more gracefully. In prior versions, long commands could damage adjacent memory and lead to difficult to diagnose failures. [UNIX] (C9J09-003199)

     

    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:

    • A database upgrade was performed but the trigger code was not updated to eliminate obsolete syntax
    • The portion of the database holding the trigger definitions may be corrupted

    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:
     
    • Usually, it is more efficient and responsive for an application to wait and process input in larger chunks. Therefore, a larger value for MOREREADTIME can bring larger chunks of input to the application. However, large values may make for sluggish response.
    • A short value for MOREREADTIME may consume considerable CPU cycles, especially on a lightly loaded system.
    • The maximum value of MORETREADTIME is 999 (basically 1 second). Never set MOREREADTIME to 0 as it causes excessive CPU "spinning".
     

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



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

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

    Copyright A(C) 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.Ma?c 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.


    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity.  Refer to the GT.M Triggers Technical Bulletin for details.


      Please note: FIS considers the implementation of triggers in V5.4-000/V5.4-000A to be robust, and entirely appropriate for development and testing short of production deployment.  With the next release of GT.M, they will have had gone through many more cycles of automated regression testing under a broader range of conditions, and will be considered production grade at that time.  If you are an FIS customer and are ready to deploy in production an application that uses GT.M triggers, please contact your FIS account manager about the timing and availability of a GT.M release in which triggers will be considered production grade.  Depending on circumstances, we may even decide then that the implementation of triggers in V5.4-000/V5.4-000AA is robust enough for production.  Except for the triggers functionality, everything else in V5.4-000/V5.4-000A is considered production grade.


    • MUPIP INTEG can now check a database for structural integrity while applications continue to operate.  In prior releases of GT.M, MUPIP INTEG would freeze updates.  Online operation is now the default for databases that contain no version 4 format database blocks.

    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.

     

     

    Return to Table of Contents

    Platforms

    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 Programmera??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 componentsa?? 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 a??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 a??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 a??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 a??UPGRADE in either of the following situations:
     
    • A database was created by a V5 MUPIP CREATE
    • A database has previously been completely processed by a MUPIP REORG a??UPGRADE from V5.3-003 or later
     
    If you have already run the MUPIP REORG a??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:
     
    • Run the MUPIP REORG a??UPGRADE command again
    • Run the DSE CHANGE a??FULLY_UPGRADED=1 command to stop the warnings
       
      Caution: Do not run the DSE CHANGE -FILEHEADER a??FULLY_UPGRADED=1 command unless you are absolutely certain you have previously successfully run to completion MUPIP REORG a??UPGRADE from V5.3-003 or later. Using this command when inappropriately may lead to database integrity issues.

     

    For additional upgrade considerations, see "Database Compatibility Notes".  
     
    Database Compatibility Notes
    • Changes to the database file header may occur in any release.  GT.M automatically upgrades database file headers as needed.  Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.
    • Databases created with V5.3-004 and later can grow to a maximum size of 224M (234,881,024) blocks.  This means, for example, that with an 8KB block size, the maximum database file size is 1,792GB (this is the size of a single global variable; a database consists of any number of global variables).  A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128M to 224M blocks.
    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128M (134,217,728) blocks.  Until and unless a database created with V5.3-004 (or later), or created in V5.0-000 through V5.3-003, exceeds the 128M block limit of earlier V5 GT.M releases, it can be accessed by releases V5.0-000 through V5.3-003. 

    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:


    • On AIX systems, if you upgrade from 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later
    • On Linux systems, if you upgrade from a 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later or from a 64-bit release to a newer 32-bit release
    • On Sun SPARC Solaris, if you upgrade from 32-bit pre-V5.3-003 to 64-bit V5.3-003

     

    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: 

     
    • Create a fresh backup of your database.
    • Generate new journal files (without back-links).

     

    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 a??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 a??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.

     

     
    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M.  GT.M itself does not have any knowledge of specific terminal control characteristics.  Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal.  You may need to add new terminfo entries depending on their specific platform and implementation.  The terminal (emulator) vendor may also be able to help.
    • GT.M uses the following terminfo capabilities.  The full variable name is followed by the capname in parenthesis:
      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

     

    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:
     

    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

    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity. Refer to the GT.M Triggers Technical Bulletin for details.


      A MUPIP RECOVER which stops due to an error before making any database modifications also leaves the file header unchanged. Previously, MUPIP RECOVER marked the database header with the "corrupt" flag and did not clear it for that case. (S9I08-002695)

    • GT.M no longer issues JNLCNTRL errors when VIEW "JNLWAIT" commands are executed after a journal file switch. Previously, in rare cases, GT.M incorrectly issued a JNLCNTRL error. (S9I09-002699)

    • GDE now preserves the mapping of multiple lexically adjacent maximum length global names. In prior versions, GDE created such ranges correctly but lost track of them when reloading the global directory for examination or a subsequent update. The workaround was to always reestablish such ranges after invoking GDE. This issue was reported from a pre-V5 environment where the maximum name length was eight characters rather than the current 31 characters. There is less chance of encountering this issue on versions V5.0-000 and later. (S9K02-002754) V5.4-000A

    • GT.M now ensures $INCREMENT() produces a numeric result even when the first argument is an undefined global variable and the second argument is a string containing non-numeric characters. Prior versions returned a string in this condition. If the first argument was a local variable, this worked properly in earlier versions. Note while the case in question is unusual enough to be unlikely, any code that relied on the prior behavior needs updating. (C9F07-002746)

    • GDE now ignores blank lines in command files. After being interrupted while processing a command file, it also properly closes the file and appropriately resumes the next action. In prior versions, GDE treated blank lines as errors and could fail with a GDECHECK error if a command file was interrupted at certain points with <CTRL-C>. (C9H10-002920) V5.4-000A

    • A GT.M process now reports a more helpful ERR_REQRUNDOWN error when it fails to attach to a shared memory segment (because of a prior improper shutdown e.g. kill -9). On detecting such a situation, prior versions instead reported the less helpful ERR_DBFILERR. [UNIX] (C9J08-003178)

    • As long as the operating system permits the access, GT.M now allows access to database files and journals in cases where the system has no user or group information available for the file. Such an unusual situation can arise, for example, when the user and group are provided via NIS, but if NIS is not currently operational the owner and group cannot be determined; or perhaps a user id is deleted while the GT.M process is active. V5.3-004[A] issued a signal-11 in such a case. [UNIX] (C9J09-003198)

    • GT.M now properly releases memory in response to a gtmcrypt_close() function call. Previously, depending upon how quickly memory was re-allocated, a gtmcrypt_close() function call could result in a signal 11 causing GT.M to abnormally terminate. [Unix] (C9J09-003190)

    • GT.M now maintains database integrity even when multiple GT.M processes simultaneously attempt to create the same global variable. This fixes a regression in GT.M V5.3-000 (also present in V5.3-004A and introduced as part of the fixes to C9H09-002901) where, in such situations, it was possible under rare circumstances for the GT.M process to cause database damage (for example, DBINVGBL or DBKEYORD errors). Note that this was an issue only for non-TP updates, that is those which were not surrounded by a TSTART/TCOMMIT. (C9J10-003202)

    • Using "" as the last subscript in a global argument to $ORDER(gvn,-1) or $ZPREVIOUS(gvn) now maintains $REFERENCE correctly. This fixes a regression introduced in GT.M version V5.3-004 (and present in V5.3-004A) as part of the fix for C9E10-002648. (C9J10-003203)

    • GT.M now deals correctly with a set of rare cases where it could inappropriately interpret negative numbers in database block control structures as large positive numbers. Previous versions might terminate with memory access violations, or get into indefinite or inappropriately long loops. This was discovered in testing DSE against a database with intentionally inflicted damage, which we expect is characteristic of the unusual conditions that might expose this issue. (C9J10-003208)

    • GT.M now correctly implements an optimization (that avoids unnecessary global variable tree traversals) for TP transactions. This fixes a regression introduced in GT.M V5.3-004 (and present in V5.3-004A) which in rare cases could cause an incorrect TPFAIL error to be issued (note: this regression did not affect the integrity of the database). (C9J11-003214)
    • GT.M now correctly handles a case where a TP transaction updates the same block, holding the same global multiple times, along with updates of blocks of other globals, and some other process, most likely MUPIP REORG, replaces the block in question with an almost identically configured block from another global in the transaction between the first and second updates of the original block. In previous versions, it was possible for this unusual combination of conditions to cause an incorrect update. The likelihood of this issue increased due to a recent change (C9905-001119) in GT.M V5.3-004 which enabled a global reference caching optimization for TP. (C9K01-003220)


    Return to Table of Contents

    M-Other Than Database Access

    • GT.M now issues a LOCKSPACEFULL error to the application and the operator log when the environment attempts more concurrent M LOCKs than the configured LOCK_SPACE for the region can support. Previously under these conditions, GT.M gave a fatal GTMASSERT error. (S9C11-002251)

    • GT.M now reports an error if the first argument of a two argument $GET() is defined and the second is an undefined local variable. Prior versions returned the value of the first argument and ignored the error mandated by the standard. If the second argument was a global variable, this worked properly in earlier versions. Note that any code that relies on the prior behavior needs updating. (S9D08-002354)

    • GT.M now reports UNDEF errors when it encounters an undefined variable specified for a local variable subscript as it already does for a global variable and as defined in the language standard. In prior versions, KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY() ignored these errors. Under NOUNDEF operation this change has no user impact. Note: code that relied on the earlier non-standard behavior may now give errors and require revision.

      GT.M now supports VIEW "NEVERLVNULLSUBS" to issue the LVNULLSUBS error for any inappropriate use of empty string subscripts in local arrays.  The [new] gtm_lvnullsubs UNIX environment variable can have the values 0 - equivalent to VIEW "NOLVNULLSUBS", 1  (the default) - equivalent to VIEW "LVNULLSUBS" or  2 - equivalent to VIEW "NEVERLVNULLSUBS". In VMS, the initial state of this characteristic is controlled by the GTM$DEFAULTS file. An empty string as the last subscript in $ORDER() and $QUERY() has the semantic significance of requesting the next lexical item and is not subject to NULLSUBS errors. $VIEW("LVNULLSUBS") returns the corresponding numeric value. In prior versions, GT.M only supported NOLVNULLSUBS, which reported the LVNULLSUBS error for SET commands that would have instantiated a prohibited local array subscript, but not for KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY().  $VIEW("LVNULLSUBS") returned 0 for NOLVNULLSUBS and 1 for LVNULLSUBS. Note that code that expected $VIEW("LVNULLSUBS") to provide a truth value must be revised. Empty string subscript checking for global variables is controlled by a database region characteristic that was already comprehensive and is not affected by this change. Note that programs using empty subscripts for references where those references cannot possibly exist are wasting computer resources, so FIS recommends using LVNULLSUBS or NEVERLVNULLSUBS for local variables and NULLSUBS options ALWAYS or NEVER for global variables. (S9D10-002376) V5.4-000A

    • If the OPEN or USE for a SOCKET device does not specify a MOREREADTIME parameter, any READ uses an initial 200msec internal timeout to minimize CPU load. Subsequent attempts to acquire more characters to fulfill the same READ use a 10msec internal timeout. When a MOREREADTIME parameter specifies a value, READ uses that value exclusively. Previously READ used a default of 10msec when no MOREREADTIME parameter was specified and consequently could consume considerable CPU cycles, especially on a lightly loaded system. If your application currently uses the MOREREADTIME parameter, FIS suggest that you consider whether this new behavior provides better performance and/or reduces CPU usage and allows you to avoid specifying MOREREADTIME. (S9J07-002732)

    • The distribution tar file now provides all files owned by the innocuous user:group ids 40535:40535, with no executable or writable files. With the exception of AIX, no directories have write permissions. On AIX, unpacking the distribution file no longer requires root permissions. In prior versions, the configure script adjusted the authorizations, but the distribution had various settings, and, on AIX, required root access to unpack the distribution. [UNIX] (S9J07-002737)

    • GT.M now handles the OPEN of a PIPE device better in certain situations. In prior versions, specifying various device parameters such as ESCAPE for the $PRINCIPAL device when it was a terminal could result in delays or other problems. [UNIX] (S9J11-002749)

    • GT.M now ensures a proper value for $QUIT on x86 and x86-64 GNU/Linux. In V5.4-000 under certain circumstances, it could return an inappropriate result. [x86-64 Linux, x86 Linux] (S9K02-002755) V5.4-000A

    • On compiling an M program, GT.M now omits reports showing the point in the line of code that caused the warning or error for lines longer than 1023 characters; it still reports the line number and column number. In prior versions, attempts to report such long lines could overrun an internal buffer and cause the process to hang or fail. (S9K02-002756) V5.4-000A

    • GT.M now correctly detects an attempt to SET a variable with an "NULL" subscript resulting from an undefined variable when using a VIEW "NOLVNULLSUBS", "NOUNDEF" combination. In versions starting with V5.3-001, the changes associated with C9B03-001664 exposed a latent problem such that GT.M did not detect a SET using an undefined local variable as a subscript as an error, but instead could use an indeterminate value for the subscript. (S9K03-002759) V5.4-000A
    • GT.M now uses buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting. While the performance difference of the buffered read approach is significant, most applications limit their use of the affected features so the overall effect may not be noticeable. Previously, GT.M used unbuffered reads which used many system calls. [UNIX] (S9K03-002761) V5.4-000A

    • The TRUNCATE parameter on USE for sequential file devices now works correctly for Linux. In prior versions, USE could truncate at the wrong position. [Linux] (C9E02-002513)

    • The GT.M SOCKET device behavior has improved in a number of ways.

      SOCKET CONNECT operations now respond to MUPIP INTRPT; in prior versions they did not.

      If the command does not specify a timeout, a SOCKET OPEN now waits for the connection to complete or an interrupting event that terminates the attempt. After an interrupt that does not terminate the connection attempt, such as the default value of $ZINTERRUPT ("IF $ZJOBEXAM()"), the process resumes the wait when the XECUTE of the $ZINTERRUPT completes. Previously, an untimed SOCKET OPEN <device>:CONNECT would make a single attempt to connect and return whether or not it was successful, as if it had a timeout of 0.

      SOCKET CONNECT status values EINPROGRESS, EWOULDBLOCK and, on some platforms, EALREADY now wait for the connection to complete or for the specified timeout to expire.  Previously, GT.M treated these conditions as errors.

      If IOERROR="TRAP" is specified on a SOCKET OPEN or USE, it now invokes any active EXCEPTION, $ETRAP, or $ZTRAP if an error occurs on a CONNECT.  The above status values as well as ECONNREFUSED and ETIMEDOUT are not considered as errors.  Previously, status values other than ECONNREFUSED or ETIMEDOUT would always be treated as errors regardless of the IOERROR value. (C9D07-002356, C9H06-002868)

    • GT.M now allows only a single set of gtm_init/gtm_exit per process and any attempt to call gtm_init/gtm_ci after a gtm_exit returns the code associated with the CALLINAFTERXIT error. Earlier GT.M versions also did not support invoking gtm_init or gtm_ci after a gtm_exit but did not enforce the restriction.[UNIX] (C9H07-002875)

    • GT.M now preserves all terminal input when handling an INTRPT in UTF-8 mode. In addition, INTRPT handling now preserves and restores the INSERT terminal characteristic. In prior versions, there was a slight chance a few characters of UTF-8 mode terminal input for either a READ or Direct Mode input could be lost and/or that the INSERT setting would revert to the default after the INTRPT event. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9H10-002913)
    • GT.M handling of INTRPT processing now protects the values of $ECODE and $STACK() at the time it recognizes the INTRPT. Prior versions allowed the code invoked by the $ZINTERUPT vector to modify those values, probably unintentionally, which could lead to a confused error processing state after completion of the $ZINTERUPT action. (C9J04-003108)

    • READ from a sequential disk file in UTF-8 mode read buffers the file reads for higher throughput. In prior versions, single character reads limited performance. [UNIX] (C9J04-003118)

    • The UNIX installation script for GT.M now sets the executable bits for files such as mumps and mupip only after a successful installation. Previously, the executable bits for these files were sometimes set after an unsuccessful installation. [UNIX] (C9J06-003140)

    • Both gtmsecshr and GT.M now prevent buffer overflow by checking the length of the gtm_tmp environment variable based on the system-specific sun_path length. In recent and properly patched versions of GT.M this was done only in gtmsecshr_wrapper. [UNIX] (C9J06-003145)

    • ZSHOW and ZWRITE now display information about alias variables with no associated data provided at least two of the joined variables are selected by the command argument. In prior releases these commands displayed alias containers with no data, but not alias variables with no data. When an alias exists with no data for the command to display, GT.M holds the variable so that it can become the right-hand side of a proper SET * command. However, if the command selection criteria excludes any other alias, GT.M has insufficient information to form a valid SET * argument and does not display that alias. Alias container variables always have a default value (the empty string), so they are handled differently and display as they did before. (C9J07-003148)

    • GT.M now handles very large object files correctly on z/OS. V5.3-003[A] produced invalid object files if the generated code exceeded 32KB. [z/OS] (C9J08-003170)

    • In UTF8 mode, when the minor version is not specified in the environment variable gtm_icu_version, e.g. 3 instead of 3.6, GT.M issues an ICUSYMNOTFOUND error. Previous versions of GT.M used to issue the ICUVERLT36 error even when the major version specified was greater than or equal to 4. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9J08-003174)

    • ^%XCMD is a utility program that XECUTEs input from the shell command line and returns any error status (truncated to a single byte on UNIX) generated by that code. For example in UNIX: mumps -run %XCMD 'write "hello world",!' would produce "hello world" (C9J08-003179)

    • GT.M now correctly handles the CLOSE of a PIPE device whose STDERR device is the current device.  Prior versions issued a segmentation violation in such a case. [UNIX] (C9J09-003188)

    • The file gtmprofile, which sets up a default environment for GT.M has been completely revamped to make it more robust and to make the out-of-box GT.M experience friendlier.  gtmprofile now sets up default values for more environment variables, creates a default global directory if one does not exist and a default database with before image journaling, if one does not exist.  The new executable shell script gtm uses gtmprofile and automatically recovers the database on startup.  gtm also deletes prior generation journal and temporary files older than the number of days specified by the environment variable gtm_retention.  A new file gdedefaults specifies default values for global directories.  The new gtmprofile script is also idempotent (can be successfully rerun after an abnormal termination), unlike its predecessor.  FIS recommends that system administrators review the gtmprofile and gdedefaults files after installing GT.M, and customize them as needed.  The previous gtmprofile file remains available as gtmprofile_preV54000 - if you want to retain the previous behavior, simply replace gtmprofile with gtmprofile_preV54000.  Note that at this time, the file gtmcshrc has not been similarly revamped for csh/tcsh users (the gtm script does not depend on the underlying shell).  [UNIX] (C9J09-003197)  

    • The distribution tar file may now be installed if there is no "bin" user and/or group defined.  The operator may now enter an alternate user and/or group to own the installation and may also restrict access to this group.  Previously the installation failed if the default bin user were specified and did not exist, or if the bin group did not exist - even if another restricted group was chosen. [UNIX] (C9J09-003201)

    • The new $gtm_stdxkill/GTM_STDXKILL environment/logical variable (UNIX/VMS) which if set to "TRUE", 1, or "YES" enables the standard-compliant behavior to kill local variables in the exclusion list if they had an alias that was not in the exclusion list. GT.M default behavior for exclusive kills thus reverts to its previous behavior, not compliant with the standard, where aliases and pass-by-reference variables specified in an exlusive kill are NOT killed even if their aliases are not specified in the exclusion list. In GT.M V5.3-004 (C9B09-001754), this behavior was changed to be compliant with the standard as part of the alias variables enhancement.  Please note that the default value is FALSE, so you must explicitly ask for standard-compliant behavior. (C9J11-003211)

    • String pool expansion is now more responsive to the rate at which the application requires space for local variables. This enhancement significantly improves the performance of applications that ramp up to atypically large string pool requirements (in the hundreds of thousands of local variable nodes), while preserving the more parsimonious string pool usage of typical applications. (C9J12-003215)

    • GT.M now allows an unsubscripted local variable, alias or alias container to be returned using the QUIT * syntax to a function invocation initiated using a SET *lvn=$$func() syntax. The SET * associates the target "lvn" local variable to the data space specified by the returning QUIT *. Previously GT.M only allowed alias information to be returned using the M pass-by-reference mechanism or by an alias in scope in both the caller and called routines. Additionally, the $QUIT ISV now returns the value "11" to indicate the current routine was invoked by a SET * and is required to return an alias using a QUIT * syntax. Failure to provide a QUIT * return as requested by the invocation produces an ALIASEXPECTED error. Providing a QUIT * return when not requested by the invocation produces a QUITALSINV error. (C9J12-003217)

    • UNIX editions will not report a value for $STORAGE larger than (2GB - 1)  [2,147,483,647], even if more is available. Previous versions could fail with SEG-V (SIG-11) errors while attempting to report $STORAGE values. [UNIX] (C9K01-003225). 

    • The configure installation script now assigns the correct permissions to the gtmsecshr wrapper for a non-restricted group installation.  It also creates symbolic links required for GTM and GDE help in utf-8 mode.  Previously, the setuid bit was not set for the gtmsecshr wrapper on some platforms and [z]help would fail in utf-8 mode.[UNIX] (C9K02-002758) V5.4-000A

     

    Return to Table of Contents

    Utilities-MUPIP

    • MUPIP and GT.M now clean up temporary snapshot files from INTEG under a wider variety of conditions. In V5.4-000, stopping the INTEG with a <CTRL-C> or a signal could leave the snapshot file orphaned. [UNIX] (S9K02-002757) V5.4-000A

    • MUPIP INTEG -REGION now supports the -ONLINE qualifier. This allows checking database structural integrity to run concurrently with database updates. Previously, INTEG froze updates on each region while checking it. Online integ is not supported with the -FILE qualifier. The -NOONLINE qualifier indicates that the database should be frozen during the MUPIP INTEG operation.

      The -ONLINE qualifier is now the default for MUPIP INTEG, except for databases containing V4 blocks, for which the default is -NOONLINE. Note that databases containing V4 blocks should exist only in databases that are in the process of being migrated from V4 to V5; please complete your migration to the V5 format before using MUPIP INTEG -ONLINE.

      The environment variable GTM_BAKTMPDIR (unlike most GT.M environment variables, this is upper case; it is the same directory used for MUPIP BACKUP -ONLINE) can be used to indicate a directory where MUPIP should place the snapshot files (used by online integ). If GTM_BAKTMPDIR does not exist, MUPIP places the snapshot files in the current directory at the time you issue the INTEG command.

      As it checks each database file, MUPIP INTEG -ONLINE creates a sparse file of the same size as the database.  As each GT.M process updates the database, it places a copy of the old block in the sparse file before updating the database.  For any database blocks with a newer transaction number than the start of the INTEG, MUPIP uses the copy in the sparse file.  Thus, analogous with MUPIP BACKUP -ONLINE, INTEG reports on the state of the database as of when it starts, not as of when it completes.  Note: a command such as ls -l command shows sparse files at their full size, but does not show actual disk usage. Use a command such as du -sh to see actual disk usage.

      Temporary directory security settings must allow write access by the the MUPIP process and read access by all processes updating the database. MUPIP creates the temporary file with the same access as the database file so processes updating the database can write to the temporary file. If the database is encrypted, the updating processes write encrypted blocks to the snapshot file and the MUPIP INTEG process must start with access to appropriate key information as it does even -NOONLINE.

      Only one online integ can be active per database region. If an online integ is already active, a subsequent one issues an error and immediately terminates. If an online integ does not successfully complete, GT.M cleans it up in one of the following ways:

    •  
      • A subsequent online integ detects that an earlier one did not successfully complete and releases the resources held by the prior online integ before proceeding.
      • If a MUPIP STOP was issued to the online integ process, the process cleans up any resources it held. Note: since the process was stopped the results of the integ may not be valid.
      • A subsequent MUPIP RUNDOWN ensures the release of resources held by prior unsuccessful online integs for the specified regions.
      • For every 64K transactions after the online integ initiation, online integ health GT.M checks for improperly abandoned online integs and releases resources held by any it finds.
       
      Because the online integ (now the default for most integs) does not freeze database updates, it cannot safely correct errors in the "blocks to upgrade" and "free blocks" fields in the file header, while MUPIP INTEG -NOONLINE can correct these fields.
        
      The -ONLINE qualifier is incompatible with the -TN_RESET qualifier. In any case, there should be no need to use -TN_RESET on a GT.M V5 database. [UNIX] (C9902-000839)

    • MUPIP INTEG -TN_RESET now resets block transaction numbers and backup event recorded transaction numbers to (one) 1, and the current transaction number to two (2) which makes the backup event recorded transaction numbers more meaningful and useful. It also issues an advisory message to perform a backup. Previously the backup event recorded transaction numbers were not maintained by -TN_RESET, which meant they held inappropriate information. Note that there should never be a need for a -TN_RESET on a datbase with only V5 blocks, even when cleaning up after a runaway process. (C9B12-001842)

    • GT.M now provides a new monitoring facility for processes holding a resource for an unexpected amount of time. This facility runs a shell command or a script pointed to by the new environment variable gtm_procstuckexe when any of the following conditions occur:  


      1. An explicit MUPIP FREEZE or an implicit freeze, such as BACKUP, INTEG -ONLINE, and so on, after a one minute wait on a region. 
      2. MUPIP actions find kill_in_prog (KILLs in progress) to be non-zero after a one minute wait on a region. Note that GT.M now internally maintains a list of PIDs (up to a maximum of 8 PIDs) currently doing a KILL operation.  
      3. The BUFOWNERSTUCK, INTERLOCK_FAIL, JNLPROCSTUCK, SHUTDOWN, WRITERSTUCK and MAXJNLQIOLOCKWAIT operator messages are being logged.


      Typically, for the shell script or command pointed to by gtm_procstuckexec, you would write corrective and preventive actions or obtain the stack trace of the troublesome processes (using their PIDs). GT.M passes arguments to the shell command / script in the order specified below:


      1. condition is the name of the condition. For example, BUFOWNERSTUCK, INTERLOCK_FAIL, and so on.
      2. waiting_pid is the PID of the process reporting the condition. 
      3. blocking_pid is the PID of the process holding a resource. 
      4. count is the number of times the script has been invoked for the current condition (1 for the first occurrence).


      Each invocation generates an operator log message and if the invocation fails an error message to the operator log. The shell script should start with a line beginning with #! that designates the shell. 


      Note: Make sure you have sufficient space and permissions to run the shell command / script.


      Prior versions wait for the condition to clear and in most cases send messages to the operator log. [UNIX] [C9D08-002390]

    • MUPIP now verifies that the byte ordering (endian-ness) of a journal file matches the byte ordering of the instance on which it is running and issues an error in case of a mismatch. In prior versions, such a case of operational cross-threading caused MUPIP to fail with various complaints about the journal file format or even a memory access violation (SIG-11 or ACCVIO). (C9J04-003110)

    • The replication source server now handles database files that are in WAS_ON replication state (and in turn a journaling state of OFF) in a safe manner. If it cannot find the journal records in the journal pool, it reads as many journal records as possible from the journal file chain and when it reaches the point where journaling got turned OFF, it periodically displays a REPL_WARN message until journaling gets turned back ON and then correctly issues a NOPREVLINK error. At all points, it behaves as a read-only process as far as journaling is concerned and never switches journal files. In previous versions of GT.M, it was possible for the source server to incorrectly attempt a switch of journal files in such WAS_ON regions eventually terminating with many types of errors (JNLFILOPN etc.). (C9J07-003156) V5.4-000A

    • The messages produced by a replicating instance when the originating instance encounters a REPLINSTNOHIST error now read:

      Originating instance encountered a REPLINSTNOHIST error. JNL_SEQNO of this replicating instance precedes the current history in the originating instance file. uuuu exiting.

      Where uuuu is either a rollback or the receiver server. [UNIX] (C9J08-003166)

    • By default, a Source Server now waits for a maximum of one and a half minute per region to shutdown. In prior versions, the maximum wait period for Source Server shutdown was approximately four minutes irrespective of the number of regions. (C9J09-003195).

    • MUPIP BACKUP -REPLINSTANCE now ensures its backup of the replication instance file is in sync with all databases backed up as part of the same command. This fixes a regression introduced in GT.M V5.3-000 (and present in V5.3-004A) that could in rare cases cause REPLINSTDBMATCH error when attempting to use the backed-up instance file because it held an incorrect sequence number for a database file. A workaround for this is to recreate the instance file, as the backed up databases are correct. (C9K01-003222)[UNIX]

    • GT.M now correctly handles an unusual set of circumstances that can occur if MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE are running concurrently with M transaction processing. In V5.4-000, these unusual circumstances could cause a SIG-11. [UNIX] (C9K02-003239) V5.4-000A

     

    Return to Table of Contents

    Utilities-Other Than MUPIP

    • DSE, LKE, and MUPIP now handle unusually long command input lines more gracefully. In prior versions, long commands could damage adjacent memory and lead to difficult to diagnose failures. [UNIX] (C9J09-003199)

     

    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:

    • A database upgrade was performed but the trigger code was not updated to eliminate obsolete syntax
    • The portion of the database holding the trigger definitions may be corrupted

    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:
     
    • Usually, it is more efficient and responsive for an application to wait and process input in larger chunks. Therefore, a larger value for MOREREADTIME can bring larger chunks of input to the application. However, large values may make for sluggish response.
    • A short value for MOREREADTIME may consume considerable CPU cycles, especially on a lightly loaded system.
    • The maximum value of MORETREADTIME is 999 (basically 1 second). Never set MOREREADTIME to 0 as it causes excessive CPU "spinning".
     

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



    \ No newline at end of file diff --git a/articles/GTM_V6.3-000_Release_Notes.html b/articles/GTM_V6.3-000_Release_Notes.html index d0a7f96..c4f10b9 100644 --- a/articles/GTM_V6.3-000_Release_Notes.html +++ b/articles/GTM_V6.3-000_Release_Notes.html @@ -300,8 +300,8 @@ tar -xvf source.tar

  • Follow the instructions in

    Summary

    -

    GTM-5007

    C9D07-002329

    Admin

    MUPIP JOURNAL parallelization option, sorted lost and broken transaction files, and change in default of -verify [!New Feature!]

    GTM-5726

    S9F07-002557

    Admin

    See GTM-7768

    GTM-6114

    C9I01-002943

    Language

    ZMESSAGE handles indirection

    GTM-6301

    C9I12-003057

    DB

    Cleaner and quicker database cleanup on process exit

    GTM-6310

    C9I12-003066

    Admin

    Change database file encryption keys "on the fly" while databases are in use [!New Feature!]

    GTM-6317

    C9J01-003070

    Admin

    See GTM-8137

    GTM-6388

    C9J05-003131

    Admin

    MUPIP EXTRACT and MUPIP JOURNAL -EXTRACT performance improvement

    GTM-6858

    S9L07-002825

    Admin

    Building ICU on AIX no longer required [!New Feature!]

    GTM-6928

    -

    Admin

    ZEROBACKLOG qualifier to shut down Source Server when backlog is zero [!New Feature!]

    GTM-7060

    -

    Language

    Better behavior when a USE command puts $X beyond WIDTH [!New Feature!]

    GTM-7199

    -

    Other

    DSE ALL -CLEARCORRUPT clears the CORRUPT flag on all regions

    GTM-7291

    -

    Admin

    MUPIP JOURNAL -ROLLBACK -FORWARD and enhancements to MUPIP JOURNAL -ROLLBACK -BACKWARD [!New Feature!]

    GTM-7375

    -

    Admin

    More tolerant ICU specification [!New Feature!]

    GTM-7604

    -

    Language

    $ZWRITE() can go from, as well as to, ZWRITE format [!New Feature!]

    GTM-7608

    -

    DB

    Processes with read-only access leave shared memory intact for databases not shutdown in an orderly fashion

    GTM-7658

    -

    Other

    Enhancements and fixes to ^%RI utility [!New Feature!]

    GTM-7762

    -

    Language

    Compiler evaluation of some operations and functions containing string literals [!New Feature!]

    GTM-7768

    -

    Admin

    Improved Source Server communication management

    GTM-7809

    -

    Admin

    Addition critical section tuning options [!New Feature!]

    GTM-7831

    -

    Admin

    Online Rollback avoids inappropriate Instance Freeze on DBDANGER

    GTM-7838

    -

    Admin

    Replication Flow Control adjustment

    GTM-8009

    -

    Other

    Prevent inappropriate file sharing after process creation

    GTM-8020

    -

    Admin

    MUPIP LOAD accepts unquoted negative values

    GTM-8022

    -

    Other

    ^%GI accepts records up to the maximum string length [!New Feature!]

    GTM-8028

    -

    Other

    Encryption plugin loads correctly for UTF-8 mode processes with standard GT.M installation directory structure

    GTM-8034

    -

    Language

    On the JOB command, enable naming of both output and error when appending JOBPID [!New Feature!]

    GTM-8038

    -

    Language

    $ZCONVERT(...,"T") works in M mode

    GTM-8076

    -

    Other

    Journal Pool Recovery

    GTM-8112

    -

    Language

    Appropriate handling by the ZSYSTEM command of a very long SHELL environment variable

    GTM-8117

    -

    DB

    Better initialization vector available for encrypted databases [!New Feature!]

    GTM-8137

    -

    Admin

    Allowing more than 32Ki processes to access the database and journal pool [!New Feature!]

    GTM-8190

    -

    DB

    Optional logging of non-tp restart conflicts [!New Feature!]

    GTM-8215

    -

    Language

    $ZCONVERT() raises ICUERROR if ICU library is unavailable

    GTM-8223

    -

    Admin

    MUPIP LOAD recognizes a wider range of labels and also DOS-formated records [!New Feature!]

    GTM-8225

    -

    Admin

    GT.M uses the default zlib on AIX [!New Feature!]

    GTM-8296

    -

    Language

    Version-agnostic invocation of $ZPEEK() with ^%PEEKBYNAME wrapper [!New Feature!]

    GTM-8297

    -

    Language

    JOBLVN2LONG message contains length information

    GTM-8302

    -

    Language

    TLS Socket renegotiation and other features for server implementation [!New Feature!]

    GTM-8326

    -

    Admin

    Allow journal pool size to be greater than 2GB

    GTM-8336

    -

    DB

    Performance improvement initializing encryption for databases with multiple encrypted regions

    GTM-8340

    -

    DB

    Receiver, Update Process, and Update Writer Helper Improvements [!New Feature!]

    GTM-8342

    -

    Admin

    Better MUPIP TRIGGER delete confirmation interaction [!New Feature!]

    GTM-8352

    -

    Language

    Improved UTF-8 character handling for $EXTRACT() and $FIND() [!New Feature!]

    GTM-8361

    -

    Admin

    Reference implementation of encryption plugin included only as source code [!New Feature!]

    GTM-8389

    -

    Language

    Source references in triggers outside of explicit TP use any available cached source [!New Feature!]

    GTM-8394

    -

    Admin

    Add robustness to ROLLBACK/RECOVER for an operationally odd case

    GTM-8395

    -

    Other

    Restore patience for startup of gtmsecshr

    GTM-8397

    -

    Language

    Ensure proper delivery of any process termination messages

    GTM-8399

    -

    DB

    Better deletion of malformed trigger representations

    GTM-8403

    -

    Other

    The %MPIECE utility NEWs all local variables

    GTM-8404

    -

    Language

    Calls to $TEXT() that are known at compile time are treated as literal strings [!New Feature!]

    GTM-8407

    -

    Language

    Correct indirection for ZSHOW

    GTM-8410

    -

    Admin

    Fix Source Server journal switch race

    GTM-8416

    -

    Other

    Better alignment of $HOROLOG and journal time stamps

    GTM-8417

    -

    Language

    Fix for ZPRINT edge case involving triggers, indirection and source file instability

    GTM-8420

    -

    Admin

    See GTM-7658

    GTM-8421

    -

    Admin

    Receiver Server started with -autorollback continues when an online rollback does not change the state of the database

    GTM-8422

    -

    Admin

    See GTM-6388

    GTM-8423

    -

    Admin

    The Receiver Server appropriately handles transactions larger than 2MiB

    GTM-8425

    -

    Admin

    Fix an evil interaction between the Update Process and Online Rollback

    GTM-8428

    -

    Admin

    MUPIP INTEG correctly reports large values for things it counts

    GTM-8429

    -

    Other

    Correction to open source builds

    GTM-8431

    -

    Language

    $TEXT() accepts ^GTM$DMOD and ^GTM$CI as arguments

    GTM-8433

    -

    Language

    ZSHOW expr:gvn output format change and ^%ZSHOWVTOLCL utility [!New Feature!]

    GTM-8435

    -

    Language

    Prevent a possible hang due to an externally initiated termination

    GTM-8440

    -

    Language

    Fix to handling of over-long device names

    GTM-8441

    -

    Other

    gtminstall script qualifier fixes

    GTM-8443

    -

    Admin

    Fix epoch taper rare edge case

    GTM-8448

    -

    Language

    Better handling of MUPIP STOPs

    GTM-8450

    -

    Language

    Prevent time overflows in $ZGETJPI()

    GTM-8457

    -

    DB

    Fix for an edge case in trigger delete

    GTM-8458

    -

    Other

    Address possible mis-ordering of DSE output

    GTM-8461

    -

    Admin

    Source Server reliably updates the resync sequence number in the replication instance file

    GTM-8464

    -

    Admin

    MUPIP EXTRACT on encrypted database creates valid binary extract files regardless of mapping

    GTM-8465

    -

    Language

    JOB with PASSCURLVN appropriately handles alias containers containing KILL'd alias variables

    GTM-8468

    -

    Admin

    Improved Source Server management of journal files

    GTM-8470

    -

    Admin

    See GTM-7831

    GTM-8471

    -

    Other

    gtmsecshr does not trigger false ARCTLMAXLOW warnings

    GTM-8475

    -

    Language

    Prevent a case where $ZSEARCH() could hang indefinitely

    GTM-8476

    -

    Language

    Fix for error handling in triggers on spanning nodes or spanning regions

    GTM-8477

    -

    Language

    GT.M no longer issues an inappropriate TLVLZERO error

    GTM-8478

    -

    Admin

    "Sending REPL_RENEG_COMPLETE" in Source Server log file

    GTM-8479

    -

    Admin

    MUPIP REORG really does respond to gtm_poollimit

    GTM-8480

    -

    Admin

    Minimize size of result from MUPIP BACKUP -DATABASE [!New Feature!]

    GTM-8481

    -

    Admin

    MUPIP INTEG handles a flood of DBTNTOOLG errors from the same global correctly

    GTM-8483

    -

    Language

    MUPIP JOURNAL -EXTRACT leaves journal files in a wholesome state

    GTM-8484

    -

    Language

    M compilations, trigger compilations, and online integrity checks no longer SIG-11 in rare cases

    GTM-8485

    -

    Admin

    MUPIP JOURNAL correctly issues FILEPARSE errors for invalid paths

    GTM-8486

    -

    Language

    ZROSYNTAX errors do not cause segmentation violations

    GTM-8487

    -

    Admin

    No more inappropriate REPLINSTMATCH errors

    GTM-8489

    -

    DB

    Prevent inappropriate Source Sever termination

    GTM-8490

    -

    Language

    VIEW command does not accept 0 and 1 as arguments

    GTM-8491

    -

    Language

    Improved $ZSEARCH on AIX for non-wildcard searches

    GTM-8494

    -

    Admin

    Better maintenance of an Instance file by MUPIP BACKUP and MUPIP REPLIC

    GTM-8495

    -

    Other

    Improve DSE key interpretation of damaged blocks under some circumstances

    GTM-8499

    -

    DB

    Unusual sequence of KILLs does not result in process termination with SIG-11

    GTM-8500

    -

    DB

    Deadlock recovery for the internal locks

    GTM-8501

    -

    DB

    Fix for NOCHLEFT error during process shutdown

    GTM-8502

    -

    Admin

    MUPIP standalone commands use the same caution as MUPIP RUNDOWN [!New Feature!]

    GTM-8506

    -

    DB

    Prevent trigger problem from causing a deadlock

    GTM-8507

    -

    Admin

    Fix rare case that inappropriately terminated replication between two SI nodes

    GTM-8511

    -

    Other

    Allow DSE to map resource even if they don't match the file header

    GTM-8512

    -

    Language

    JOB command uses $zgbldir as the default value for the command parameter GBLDIR

    GTM-8514

    -

    Other

    −−xec is optional for %XCMD

    • Database

    • Processes execute substantially less logic when exiting database files opened with the BG access method. Previously process exit involved more checking, which could significantly slow the exit and consume CPU resources potentially usable by other processes, behavior which was most visible when a large number of processes concurrently attempted to exit databases with large numbers of regions and large numbers of global buffers per region. (GTM-6301)

    • A process with read-only access run on an otherwise unaccessed database that was not shutdown in an orderly fashion, due to for example a kill -9, attached processes exceeding 32Ki, etc., leaves shared memory intact. Previously, such a process could cause the loss of the shared resource and, under some circumstances, updates it contained. (GTM-7608)

    • GT.M uses non-zero, context-sensitive, initialization vectors (IVs) when it encrypts or decrypts databases, journal files, binary extracts and bytestream backups; previously it used empty (all zeros or "NULL_IV") initialization vectors.

      MUPIP EXTRACT -FORMAT=BIN accepts a -NULL_IV qualifier and generates extracts in the following formats:

      • Level 6 for extracts that include no encrypted region (i.e., no data in the extract is encrypted). This is unchanged from prior releases.
      • Level 8 for extracts that include at least one encrypted region (i.e., some or all data is encrypted), and the extract was generated either (a) with the -NULL_IV flag, or (b) from database regions that are encrypted with null IVs, to generate a file with null IVs. MUPIP LOAD from GT.M V6.2-002/-002A can load level 8 extracts (but see the discussion of GTM-8360 in the V6.2-002 release notes on extracts that mixed encrypted and unencrypted regions in GT.M releases prior to V6.2-002)
      • Level 9 for extracts that include at least one encrypted region, and the extract uses IVs - i.e., MUPIP LOAD only from V6.3-000 and future releases will be able to accept this format.

      MUPIP BACKUP -BYTESTREAM in V6.3-000 uses level format 8 for an encrypted region and level format 9 for an unencrypted one (i.e., the first 5 characters of the label are "GDSV8" or "GDSV9", respectively). Bytestream backups created from a database with a particular minor version can only be restored onto a database with the same minor version. In case of a minor version mismatch GT.M issues the MUPRESTERR error with a descriptive addendum.

      Journal and database file header dumps, produced using MUPIP JOURNAL -SHOW=HEADER and DSE DUMP -FILE -ALL, respectively, report whether an all-zero IV (NULL_IV) is in use.

      Additionally, ZSHOW "D" displays the name of the encryption key and IV type for each file device that has its input, output, or both streams using encryption.

      Please note:

      • For databases created with prior versions that used an all-zero IV, GT.M continues to provide an empty IV for database blocks and journal records (see the release note for GTM-6310 on upgrading to non-zero IVs).
      • To downgrade a database that uses non-zero IVs to a database that uses zero IVs, extract the contents with MUPIP EXTRACT and use MUPIP LOAD to load the contents into a database created with a prior GT.M version that uses zero IVs. If the MUPIP LOAD targets a prior version of GT.M, the extract needs to either specify FORMAT=ZWR or FORMAT=BIN -NULL_IV.
      • While GT.M releases that provide non-zero IVs can use databases from versions of GT.M that use zero IVs, prior versions of GT.M that use zero IVs cannot process files that have non-zero IVs (e.g., while MUPIP LOAD can process binary extracts in the prior GDS level 8 format, previous GT.M versions cannot process GDS level format 9 binary extracts).

      (GTM-8117) [!New Feature!]

    • V63-000A Processes starting up with an Instance Freeze in place can proceed up to their first attempt to perform an update. Previously, if all processes accessing a database region which was a member of a frozen instance had been shut down with a SIGTERM, subsequent processes could hang attempting to connect to that database region, even if their actions did not involve updates. This issue was partially addressed in V6.3-000, but the Source Server could incorrectly rundown database regions on frozen instances, leading to the hang. (GTM-8177)

    • The gtm_nontprestart_log_delta and gtm_nontprestart_log_first environment variables control whether and how GT.M sends to the syslog NONTPRESTART messages that supply information on non-TP "mini transaction" restarts. If $gtm_nontprestart_log_delta is a non-zero integer, GT.M uses the value as a sampling interval for the messages, so a value of one (1) produces a report for every non-TP restart, a value of two (2) means a report for every other non-TP restart, etc. If $gtm_nontprestart_log_delta is defined as described and $gtm_nontprestart_log_first is also a non-zero integer, GT.M reports the first $gtm_nontprestart_log_first non-TP restarts before reporting samples as defined by $gtm_nontprestart_log_delta. Previously, GT.M did not provide detailed information for non-TP mini-transactions, but it did provide cumulative restart non-TP mini-transaction restarts using the NR0, NR1, NR2, NR3 fields in the ZSHOW "G" output. In addition, if the restart occurs due to a conflict in the global directory tree, the TPRESTART message reports "*DIR" for the glbl field. Previously, in that case, it displayed only "^" with no global variable name. TPRESTART messages include the subscript of the contested global. Previously, it reported global names without any subscript information. VIEW [NO]LOGN[ONTP][:intexpr] allows a process to dynamically change the logging to the syslog of NONTPRESTART messages established at process startup by the environment variables gtm_nontprestart_log_delta and gtm_nontprestart_log_first. VIEW "NOLOGNONTP" turns off the logging of NONTPRESTART messages to the syslog. VIEW "LOGNONTP"[:intexpr] turns on logging of NONTPRESTART messages to the syslog. If no intexpr is specified, GT.M uses the value of environment variable gtm_nontprestart_log_delta, if it is defined, and one (1) otherwise (that is, log every transaction restart). A negative value of intexpr turns off the logging of NONTPRESTART messages. Note that it is not possible to perform the operations of gtm_nontprestart_log_first with VIEW "LOGNONTP"[:intexpr]. (GTM-8190) [!New Feature!]

    • Encryption initialization is faster for databases with multiple encrypted regions, with the improvement more noticeable as the number of regions increases. To facilitate this performance improvement, GT.M requires the encryption configuration file (referred to by $gtmcrypt_config) to specifically associate the key used by each database file with that database file name, raising an error if an entry mapping the key to the file does not exist. Previously, GT.M accepted any key with a hash matching that in the database file header, even a key that was not specifically mapped to a database file name that used it. This enhancement benefits from changes to the API of the encryption plugin. (GTM-8336)

    • Update helper writer processes increase replication throughput, decrease backlog, and improve manageability:

      • Update writer helper processes start flush timers, participate in epoch tapering, and perform timed epochs. Previously writer helpers only flushed dirty blocks.
      • The Update Process no longer starts or restarts flush timers on a database if there is another process with a timer, e.g. an update writer helper. Previously the Update Process typically would establish a timer, preempting writer helpers from performing them.
      • The Receiver Server actively notifies the Update Process when there is work to be done. Previously the update process periodically polled for updates when the receive pool backlog reached zero, potentially leading to short periods where the backlog increased.
      • MUPIP REPLICATE -RECEIVER -SHUTDOWN shuts down update helper processes left running after the receiver shutdown abnormally. Previously a prior MUPIP REPLICATE -RECEIVER -SHUTDOWN -HELPERS was required to terminate each such process.

      (GTM-8340) [!New Feature!]

    • $ZTRIGGER() and MUPIP TRIGGER delete all, "-*", operations delete malformed trigger records, identifying such malformed trigger records with TRIGDEFBAD warnings. Previously trigger delete ignored some malformed triggers making them undeletable. In some cases, attempts to view (SELECT) these malformed triggers failed, making them invisible as well. The workaround was to extract all triggers to a file, add a trigger for each global variable with a trigger, followed by a delete all, "-*". This deleted all triggers and restored the desired triggers in one transaction. (GTM-8399)

    • $ZTRIGGER()and MUPIP TRIGGER appropriately delete triggers as specified; previously under rare circumstances, they silently failed to do so. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8457)

    • Processes that have read-write access to a journaled database file, but have not yet performed any updates to it (i.e., processes that have not yet opened the journal file for that database file), cooperate correctly with processes that have read-write access and have performed updates. Previously, it was possible for the former to pick up all available slots for flushing dirty buffers (the default being two slots), resulting in an out-of-design situation where dirty buffers did not get flushed in a timely manner, in turn resulting in the Source Server terminating with a SEQNUMSEARCHTIMEOUT error. Additionally, the Source Server issues an alert every 50 seconds (instead of 10 seconds previously). (GTM-8489)

    • KILL of a global outside of a TP transaction following a large TP transaction with certain characteristics by the same process works correctly; previously this unusual sequence could terminate a process with a segmentation violation (SIG-11). Database structural integrity was not at risk from this behavior. (GTM-8499)

    • GT.M does not internally deadlock in the presence of certain rare, asynchronous events, as it previously could in releases V6.0-003 through V6.2-002A. This issue was only observed in the GT.M development environment, and was never reported by a user. Note that the design of GT.M precludes deadlocks in normal usage. (GTM-8500)

    • MUPIP, LKE, and DSE no longer issue NOCHLEFT fatal errors while handling errors in database disconnect which occur during process shutdown. (GTM-8501)

    • GT.M processes no longer deadlock when a trigger causes a fatal error, under certain unusual conditions. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8506)

    • V63-000A TP transactions work appropriately for MM access databases when there is a concurrent database file extension. Previously, in rare cases these circumstances caused GT.M to terminate with a segmentation violation (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8523)

    • V63-000A GT.M issues a JNLPOOLSETUP error if/when 32Ki processes open the journal pool and the corresponding replication instance file does not have -qdbrundown enabled. In GT.M V6.3-000, the GT.M process used to terminate abnormally with a SIG-11 while trying to issue the error. (GTM-8535)

    • V63-000A Replication works correctly when the replication instance file has -qdbrundown enabled and some processes in the instance have read-only access to the replication instance file. In V6.3-000, if the 32,768th process accessing the instance had read-only access to the replication instance file, it would issue a REPLINSTOPEN error, and hold internal locks on the Journal Pool and instance file, resulting in hangs and MUTEXLCKALERT messages from other processes. A value of 1 returned by $$^%PEEKBYNAME("node_local.ftok_counter_halted",region) means that the number of processes accessing the region ever reached 32,768, resulting in the counter no longer being maintained. Similarly, a value of 1 returned by $$^%PEEKBYNAME("jnlpool_ctl_struct.ftok_counter_halted") means that the number of processes attaching to the Journal Pool reached 32.768, again resulting in the counter no longer being maintained. A value of TRUE in the "CTL FTOK Counter Halted" field of the output from MUPIP REPLIC -SOURCE -JNLPOOL -SHOW also shows the Journal Pool information. DSE and LKE now send any RESRCWAIT messages to the syslog. Previously, they used to display such messages in their output. (GTM-8538)

    • V63-000A With epoch tapering enabled, GT.M issues a single fsync in preparation for an epoch; previously it could issue a number of fsyncs prior to the epoch. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8539)

    • V63-000A LOCK (and ZALLOCATE) issue a LOCKTIMINGINTP warning message to the syslog when a process fails to acquire a LOCK within a critical resource holding retry of a TP transaction. Unlike TPNOTACID warnings, which signal the release of critical resource, LOCKTIMINGINTP does not indicate a release of resources. Such a LOCK must have a timeout less than gtm_tpnotacidtime, or, if undefined, its default of two (2) seconds, which should limit the duration of the resource blockage it causes; a timeout of 0 (zero) prevents this warning. Note that FIS recommends avoiding the use of LOCK commands within TP transactions. Previously, the described condition produced a TPNOTACID warning with its accompanying release of resources, which made the transaction more likely to make repeated restarts. (GTM-8546)

    • V63-000A GT.M avoids holding a critical shared resource on database regions and the journal pool longer than necessary. Previously, a non-TP transaction on a replicated region which processed a timed epoch would hold the resource on the journal pool while processing the epoch, and a process in the final retry of a transaction could frequently sleep or yield the processor, potentially repeatedly, while holding the resource on the database region. (GTM-8554)

    Language

    • V63-000A GT.M is silent about implicitly assigning the current global directory to a value that identifies an inaccessible file. Note that attempting to use such a value for a global directory continues to produce a ZGBLDIRACC error. Previously, with such a $ZGBLDIR value, a QUIT after a NEW $ZGBLDIR resulted in a STACKOFLOW error and a valid external reference produced an inappropriate ZGBLDIRACC error. (GTM-4759)

    • ZMESSAGE accepts an indirect argument. Previously this syntax produced a GTMASSERT. (GTM-6114)

    • In an M mode process, a WRITE to a sequential device after a SET $X to a value greater than the device WIDTH or a reduction in WIDTH to less than the current $X acts as if the first character caused $X to exceed the WIDTH inducing an immediate WRAP, if WRAP is enabled. Previously, $X exceeding WIDTH in an M mode process caused a SYSTEM-E-ENO14, Bad address error. (GTM-7060) [!New Feature!]

    • $ZWRITE() accepts a second intexpr which specifies the direction of the conversion. No value or a zero value converts the first argument to ZWRITE format and a non-zero value converts the first argument from ZWRITE format to a string with embedded non-graphic characters. In addition, $ZWRITE() now takes the cannonical or non-cannonical nature of its first argument into account; previously it attempted to treat non-canonical numeric values as numbers rather than strings, which caused errors and inappropriate results. Also if all its arguments are literals, $ZWRITE() evaluates to a literal constant at compile time. Previously $ZWRITE only accepted a single argument, converting only to ZWRITE format, and always evaluated at run time. (GTM-7604) [!New Feature!]

    • The GT.M compiler resolves some expressions involving string literals at compile time, reducing both code size and run time CPU requirements. Currently the compiler does this for concatenation operations, $[Z]ASCII(), $[Z]EXTRACT(), $[Z]PIECE(), and $ZSUBSTR(). For code compiled in UTF-8 mode, this means that the compiler can report BADCHAR warnings for strings that are not legal UTF-8 strings, where previously it did not. The compiler flags these as warnings, rather than as errors, since the possible difference between the compile time and run time setting of [NO]BADCHAR dictates that the compiler cannot with certainty determine whether strings containing illegal UTF-8 characters are actually errors (for example, they may contain binary data). When the compiler reports BADCHAR warnings, it defers the computation to run time, instead of attempting to precompute the result. Note that sometimes a single character with an invalid encoding can cause multiple warnings, for example, when a string that is not a valid UTF-8 string appears inside a function such as $PIECE(). Regardless of any compile time warnings, there is no change to run time functionality of any M application code as a result of this change. (GTM-7762) [!New Feature!]

    • Using VIEW "JOBPID":1 does not issue an error when the JOB command parameters ERROR and OUTPUT point to the same file; previously, while the effect of the VIEW command was not documented, using the same file name for ERROR and OUTPUT and VIEW "JOBPID":1 resulted in an error. (GTM-8034) [!New Feature!]

    • $ZCONVERT(...,"T") works in M mode; previously it only worked in UTF-8 mode. (GTM-8038)

    • Processes no longer terminate with a segmentation violation (SIG-11) when:

      • executing the ZSYSTEM command with an overly long value of the environment variable SHELL; and

      • initializing the reference implementation of the encryption plugin with an overly long value of the environment variable GNUPGHOME.

      These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8112)

    • $ZCONVERT() raises an ICUERROR if GT.M is unable to correctly access the ICU library; previously the process terminated with a GTMASSERT. It also runs faster than it did previously. (GTM-8215)

    • %PEEKBYNAME() provides a stable interface to $ZPEEK() that uses control structure field mnemonics. $ZPEEK() provides a read-only mechanism to access selected fields in selected control structures in the address space of a process, including process private memory, database shared memory segments and Journal Pools. Although application code can call $ZPEEK() directly, such direct access must use numeric arguments that can vary from release to release. Access using %PEEKBYNAME makes application code more stable across GT.M releases. For more information, refer to Additional Information forGTM-8296- %PEEKBYNAME(). (GTM-8296) [!New Feature!]

    • If the JOB command finds the ZWRITE representation of an lvn consisting of a its full name, its subscripts, corresponding value, quotes and the "=" sign, exceeding 1MiB, it produces a JOBLVN2LONG error in both JOB'ing and JOB'd process' error stream. This message includes the attempted length and maximum limit. Previously, the JOB'ing process would issue a JOBLVN2LONG error without the lvn length details, and JOB'd process would issue a JOBLVNDETAIL with the length information which the JOBLVN2LONG currently displays. (GTM-8297)

    • The WRITE /TLS("renegotiate"[,,[tlsid][,,options]]) command on a server socket allows applications to request a TLS renegotiation. In the command:

      • The second and fourth arguments are unspecified.

      • tlsid refers to the name of a section in the configuration file specified by the gtmcrypt_config environment variable. If tlsid is not specified, GT.M creates a virtual section by appending "-RENEGOTIATE" to the tlsid used to enable TLS on the socket. If no section named tlsid is present in the configuration file, GT.M creates a virtual section with that name for the life of the process.

      • Supported configuration file options passed in the command are (case-sensitive): verify-depth, verify-level, verify-mode, session-id-hex, and CAfile.

      • When tlsid is specified, any options in the command take precedence over options of the same name specified in the configuration file section.

      The WRITE /TLS("renegotiate",...) command ignores options other than those listed above. The options remain in effect for the socket after the renegotiation. Any virtual section remains available in the current process.

      Renegotiation requires the suspension of application communication and the application must read all pending data before initiating a renegotiation. This means that in the communication protocol used, both parties must be at a known state when renegotiating keys. For example, in GT.M replication, one party sends a renegotiation request and waits for an acknowledgement before initiating the renegotiation.

      The configuration file can specify options, although the WRITE /TLS("renegotiate",...) command can override them. Note that configuration file options may be useful even without the renegotiate command.

      • The CAfile option when specified for a server connection either in a tlsid level configuration file section or for the renegotiate command allows the server to inform the client of acceptable certificate authorities via the OpenSSL function SSL_set_client_CA_list(). The determinant definition for the acceptable list of certificate authorities sent to the client comes in descending order of priority from the one specified by the WRITE /TLS("renegotiate",...) command, the one specified by the CAfile value in the tlsid section used to establish the TLS connection, and finally that specified at the tls level.

      • The verify-level option takes a string value to specify any additional certificate verification in addition to the basic OpenSSL verification. The only value currently accepted is "CHECK" which requests additional checks on the results of the basic OpenSSL certificate verification. A leading exclamation mark ("!") disables a verify-level option. The verify-level options specified at lower levels are merged with those options already specified at higher levels. CHECK is enabled by default for all TLS connections.

      • The session-id-hex option takes a string value which is used to set the SSL session_id context for server sockets, which may be specified in the tlsid section of a config file or on WRITE /TLS("RENEGOTIATE",...). See the OpenSSL man page for SSL_set_session_id_context for usage details. The value should consist of hexadecimal digits representing the desired value. Application code can call the %UTF2HEX utility routine to translate a character string to the corresponding string of hexadecimal digits. If neither the command or the associated tlsid section in the configuration file specify a session-id-hex option when creating the socket, GT.M uses the current tlsid, translated into hexadecimal digits.

      The default for the configuration file option verify-mode is SSL_VERIFY_PEER. Previously it was SSL_VERIFY_NONE for TLS enabled sockets.

      Including "SESSION" in the fourth argument of $ZSOCKET "TLS" returns information related to SSL sessions including information about renegotiations. The following is an example of the information returned in addition to the information previously returned:

      |S:RENSEC:1,RENTOT:1,SESSID:A9EB18B4731B2E4ABA572C8386213
-4C67C9561597D5FAF47CDD5B866B77215FF,SESEXP:Thu Jun  4 21:07:11 2015

      where "|S:" denotes this piece contains session information, "RENSEC:" indicates whether secure renegotiation is available (1) or not (0), "RENTOT:" gives the current total number of renegotiations done on this socket, "SESSID:" shows the session id in hexadecimal, and "SESEXP:" indicates when the session expires in the local timezone.

      Including "OPTIONS" in the fourth argument of $ZSOCKET "TLS" now returns the verify mode after the TLS options (that is, "|O:hexdigits") as a comma and two hexadecimal digits. The verify mode values are defined in openssl/ssl.h.

      Including "ALL" in the fourth argument of $ZSOCKET "TLS" returns all available information.

      A successful WRITE for a TLS enabled socket with an argument larger than the ZBFSIZE for the socket is not considered an error. Previously, such a WRITE indicated an error with the following $DEVICE value: "1,Unknown error -1" or if IOERROR="TRAP", $ZSTATUS included:

      %GTM-E-SOCKWRITE, Write to a socket failed,%GTM-I-TEXT, Unknown error -1

      (GTM-8302) [!New Feature!]

    • To improve performance of certain UTF-8 string functions, when a string 32-bytes or longer is passed as the first parameter to $EXTRACT() and $FIND() calls that have three parameters, GT.M caches information regarding transitions between blocks of ASCII characters ($CHAR(0) through $CHAR(127)) and non-ASCII UTF-8 characters ($CHAR(128) & up). Actual improvement in application performance can range from unobservable to dramatic depending on the prevalence of this use case. As there are a couple of tuning parameters for this optimization (with defaults that are reasonable in our judgement), if you have code that benefits from this optimization, please contact your GT.M support channel for help in experimenting with the tuning the parameters. (GTM-8352) [!New Feature!]

    • When a process accesses a trigger definition with ZPRINT or $TEXT() outside of a TP transaction and it has previously fetched the definition with no intervening execution of a revised trigger definition, GT.M returns information cached by that prior access. Previously, if another process had deleted or modified the definition after its last source access and with no intervening execution, ZPRINT gave a TRIGNAMF error and $TEXT() returned an empty string. Note that accessing the source code within a TP transaction (either implicit or explicit) always uses the current definition. (GTM-8389) [!New Feature!]

    • When interrupted by a signal requesting termination, such as SIGTERM, while writing to the principal device, GT.M prints that all subsequent rundown messages correctly. Previously, there was a small window in writing to the principal device when an external signal could result in corrupt rundown messages. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8397)

    • Calls to $TEXT() for which the compiler can determine the source code line at compile time it compiles as literal strings in the object code. Specifically, this optimization occurs when the entryref refers to a line in the current routine, and no component of the entryref uses indirection. (GTM-8404) [!New Feature!]

    • ZSHOW accepts atomic indirection in the second expression of its argument. Previously it incorrectly gave an error for such an attempt. (GTM-8407)

    • ZPRINT handles an unusual case when it appears within trigger code and also within an XECUTE or indirection and the target routine has become empty (has zero length). Previously, such circumstances intermittently produced a ZLINKFILE error. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8417)

    • $TEXT() returns the empty string for ^GTM$DMOD and ^GTM$CI; previously these $TEXT() arguments, which represent respectively the base frames for mumps -direct and a call-in and could be derived from $STACK(), $ZPOSITION or ZSHOW "S", produced an RPARENMISSING error. (GTM-8431)

    • ZSHOW expr:gvn stores continuations of information that do not fit in the maximum record size as immediate descendants, using ordinal subscripts starting at one (1), of the node holding the beginning of the information. This facilitates identifying when multiple nodes need to be reassembled to find the entire item. In addition, the ^%ZSHOWVTOLCL utility program restores ZSHOW "V":gvn data into its original local variables. The utility needs to be invoked with $ECODE set to the empty string ("") and cannot restore a local variable with the same name (%ZSHOWvbase) as the parameter in its formal list. Other ZSHOW information typically fits within common database record size limitations. Previously, ZSHOW expr:gvn stored continuation nodes at the same level as other nodes. Although this change is not backward compatible, it facilitates automated restoration even of nodes exceeding the maximum record size of the global, which was not the case previously (GTM-8433) [!New Feature!]

    • When a GT.M process receives a MUPIP STOP while doing a READ on a SEQUENTIAL, FIFO, or PIPE device in NOFIXED, M mode, the process terminates. Previously, this combination could cause the process to hang. (GTM-8435)

    • GT.M produces an appropriate error for an inappropriately long device name in the argument of OPEN, USE and CLOSE commands; previously such an argument could cause a segmentation violation (SIG-11). (GTM-8440)

    • When interrupted by a signal requesting termination, such as SIGTERM GT.M handles the termination appropriately. In GT.M V6.2-002 and V6.2-002A, if the interrupt happened during certain small windows of execution, it was possible for the process to terminate abnormally, hang, or exhibit other incorrect behavior under rare conditions. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8448)

    • $ZGETJPI() reports large values appropriately; previously large times could wrap. (GTM-8450)

    • V63-000A ZWRITE and ZSHOW "V" work appropriately after an interrupted MERGE command involving a local variable; previously this combination could cause a segmentation violation (SIG-11). (GTM-8454)

    • A JOB command with PASSCURLVN correctly passes alias containers that contain KILL'ed original aliases. Previously, JOB command with PASSCURLVN could fail with INDEXTRACHARS error in such a case. (GTM-8465)

    • $ZSEARCH() avoids a possible deadlock that could cause a process to hang indefinitely. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8475)

    • GT.M handles errors from triggers on globals that span nodes or regions when the error handler does not clear $ECODE. Previously, when a trigger's error handler did not clear $ECODE for an update to a global that spanned regions or nodes, GT.M issued a fatal GTMASSERT2 error. (GTM-8476)

    • GT.M no longer issues an inappropriate TLVLZERO error when executing a TCOMMIT command, as it previously did under certain very rare conditions. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8477)

    • MUPIP JOURNAL -EXTRACT leaves journal files in a wholesome state when run where a corresponding database was not shutdown in an orderly fashion, due to for example a kill -9, attached processes exceeding 32Ki, etc. Previously, under these somewhat unusual conditions MUPIP JOURNAL -EXTRACT left the journal files in a state where they could not be applied to recover the database. (GTM-8483)

    • M compilations, trigger compilations, and online integrity checks no longer result in segmentation faults (SIG-11) in rare cases. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8484)

    • GT.M correctly issues a ZROSYNTAX error when transitioning from a $ZROutines with auto-relink enabled to a $ZROutines that has non-existent directory paths. Previously, GT.M terminated with a segmentation violation (SIG-11). (GTM-8486)

    • GT.M treats VIEW 1 and VIEW 0 as errors. Previously, it treated these constructs as VIEW "GDSCERT":1 and VIEW "GDSCERT":0 commands respectively. (GTM-8490)

    • On AIX, for non-wildcard searches, $ZSEARCH() exhibits performance similar to that of other platforms. The correction made with GTM-8237 in V6.2-002 exposed decreased and erratic performance on AIX of the POSIX service used to perform such searches. [AIX] (GTM-8491)

    • Unless overridden with a GBLDIR jobparameter, processes started with the JOB command use the global directory specified by the $ZGBLDIR of the process executing the JOB command (as documented). Previously, these processes incorrectly used the value of the environment variable gtmgbldir in the environment of the parent executing the JOB command. As a side effect, since the process executing the JOB command would have previously validated the path to the global directory, a JOB'd processes does not terminate with a segmentation violation (SIG-11), as it previously did, if $gtmgbldir is longer than GT.M's limit of 255 bytes for the path to the global directory. You should check all occurrences in your application where it executes JOB commands without GBLDIR jobparameters when its values of $ZGBLDIR and $gtmgbldir differ. In addition, processes no longer terminate with a segmentation violation (SIG-11) when: executing the ZSYSTEM command with an overly long value of the environment variable SHELL; and initializing the reference implementation of the encryption plugin with an overly long value of the environment variable GNUPGHOME. These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8512)

    • V63-000A GT.M correctly handles pattern specifications where the pattern contains a finite pattern atom (for example 1A) followed by an infinite pattern atom with a pattern code that is a superset of the first pattern (for example .AN) and followed by an alternation (for example .(1".")). Previously it used to treat the finite pattern atom in the above specification as infinite and incorrectly merge the two treating a 1A.AN.(1".") as .AN.(1".") resulting in incorrect results. In addition, the pattern match operator run- time performance has been improved for various types of pattern expressions. (GTM-8522)

    • V63-000A If the SHELL environment variable is undefined at GT.M process start-up or if an external call unsets the SHELL enviroment variable, the ZSYSTEM command uses /bin/sh to execute the shell command. Previously, if the SHELL environment variable was undefined at GT.M process start-up, the ZSYSTEM command would fail to work, issuing a "not found" error. In GT.M V6.3-000, if an external call unset the SHELL environment variable, only the first ZSYSTEM call worked as intended. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8530)

    • V63-000A Intrinsic functions that use integer or numeric arguments actually constructed using compile-time optimizations to resolve expressions consisting entirely of literals for concatenation and some string functions in source code work as documented. For example $ORDER(xxx,"-"_"1"), where xxx is any legal first argument produced a GTM-E-ORDER2 error. Not invoking the optimization by avoiding the concatenation worked correctly - e.g., $ORDER(xxx,"-1") - as did any operation that coerced the result to numeric - e.g., $ORDER(xxx,"-"_"1"+0). Owing to a problem with string optimizations (GTM-7762 and GTM-8404) in V6.3-000 this described combination of factors generated inappropriate errors. (GTM-8540)

    • V63-000A $TEXT(x) where x is a label works correctly when there is a label xyz in the current routine (a) preceding label x and (b) where x is a leading substring of xyz. Note that $TEXT(x^routine) was not affected. Note also that "local labels," those terminated with a colon (:), are accessible at compile time, but not at run time. Owing to a bug with optimization GTM-8404 in V6.3-000, $TEXT(x) would, under these circumstances, incorrectly provide the source code $TEXT(xyz). If there were multiple labels xyz1, xyz2, etc., $TEXT(x) would provide the source code for the first, i.e., $TEXT(xyz1). (GTM-8549)

    • V63-000A When assigned to a local variable node, the result of $FNUMBER() where the second argument is the empty string and the third argument specifies potential rounding retains the value assigned. Previously in such circumstances, GT.M could subsequently alter the value in such a node to an incorrect value. The workaround was to use $JUSTIFY(x,0,n) rather than $FNUMBER(x,"",n)(GTM-8558)

    System Administration

    • MUPIP JOURNAL commands (e.g. ROLLBACK, RECOVER, VERIFY, SHOW etc.) accept the -PARA[LLEL][=n] qualifier to specify the number of parallel threads (for backward processing) and parallel processes (for forward processing). Omitting the qualifier or specifying a value of one (1) defaults to a single process with no threads. Omitting the value or specifying a value of zero (0) specifies one thread or process per region. A value greater than one (1) specifies the maximum number of concurrent threads or processes MUPIP should use, although it never uses more than one per region. If the number of regions exceeds the specified value, MUPIP allocates threads or processes in an order determined by timestamps in the journal records. The environment variable gtm_mupjnl_parallel provides a value when the command has no explicit -PARALLEL qualifier; when defined with no value gtm_mupjnl_parallel acts like -PARALLEL with no value. When the -PARALLEL qualifier (or the gtm_mupjnl_parallel environment variable) specifies the use of parallel processes in the forward phase of a MUPIP JOURNAL command, MUPIP may create temporary shared memory segments and/or extract files (corresponding to -extract or -losttrans or -brokentrans qualifiers) and clean these up at the end of the command; however an abnormal termination such as a kill -9 might cause these to be orphaned.

      Journal extract files (created by specifying one of -extract or -brokentrans or -losttrans to a MUPIP JOURNAL command) contain journal records sorted by sequence number (token_seq/jsnum) then by update order (updnum) for all regions which were replicated/journaled - in other words: in the exact order their corresponding updates happened in time. In prior versions of GT.M, these files were not sorted which meant applying lost transaction files (for example) required first sorting the file to correspond to the update-order before applying them.

      In addition, a MUPIP JOURNAL -SHOW=HEADER has default of -NOVERIFY if no other action qualifiers (-EXTRACT, -RECOVER, -ROLLBACK, -SHOW) are specified. This speeds up the command in the default case (no verification of the entire journal file occurs). Note that specifying -VERIFY explicitly still does the verification as requested. (GTM-5007) [!New Feature!]

    • See GTM-7768. (GTM-5726)

    • With the -ENCRYPT flag, MUPIP REORG changes the encryption key of a database, or encrypts an unencrypted database, while the database continues to be used by applications. Whether or not the prior encryption uses non-zero initialization vectors (IVs), database blocks encrypted with the new key use non-zero IVs (see GTM-8117). The syntax is:

      +              
      GTM-5007
      C9D07-002329
      Admin
      MUPIP JOURNAL parallelization option, sorted lost and broken transaction files, and change in default of -verify [!New Feature!]
      GTM-5726
      S9F07-002557
      Admin
      See GTM-7768
      GTM-6114
      C9I01-002943
      Language
      ZMESSAGE handles indirection
      GTM-6301
      C9I12-003057
      DB
      Cleaner and quicker database cleanup on process exit
      GTM-6310
      C9I12-003066
      Admin
      Change database file encryption keys "on the fly" while databases are in use [!New Feature!]
      GTM-6317
      C9J01-003070
      Admin
      See GTM-8137
      GTM-6388
      C9J05-003131
      Admin
      MUPIP EXTRACT and MUPIP JOURNAL -EXTRACT performance improvement
      GTM-6858
      S9L07-002825
      Admin
      Building ICU on AIX no longer required [!New Feature!]
      GTM-6928
      -
      Admin
      ZEROBACKLOG qualifier to shut down Source Server when backlog is zero [!New Feature!]
      GTM-7060
      -
      Language
      Better behavior when a USE command puts $X beyond WIDTH [!New Feature!]
      GTM-7199
      -
      Other
      DSE ALL -CLEARCORRUPT clears the CORRUPT flag on all regions
      GTM-7291
      -
      Admin
      MUPIP JOURNAL -ROLLBACK -FORWARD and enhancements to MUPIP JOURNAL -ROLLBACK -BACKWARD [!New Feature!]
      GTM-7375
      -
      Admin
      More tolerant ICU specification [!New Feature!]
      GTM-7604
      -
      Language
      $ZWRITE() can go from, as well as to, ZWRITE format [!New Feature!]
      GTM-7608
      -
      DB
      Processes with read-only access leave shared memory intact for databases not shutdown in an orderly fashion
      GTM-7658
      -
      Other
      Enhancements and fixes to ^%RI utility [!New Feature!]
      GTM-7762
      -
      Language
      Compiler evaluation of some operations and functions containing string literals [!New Feature!]
      GTM-7768
      -
      Admin
      Improved Source Server communication management
      GTM-7809
      -
      Admin
      Addition critical section tuning options [!New Feature!]
      GTM-7831
      -
      Admin
      Online Rollback avoids inappropriate Instance Freeze on DBDANGER
      GTM-7838
      -
      Admin
      Replication Flow Control adjustment
      GTM-8009
      -
      Other
      Prevent inappropriate file sharing after process creation
      GTM-8020
      -
      Admin
      MUPIP LOAD accepts unquoted negative values
      GTM-8022
      -
      Other
      ^%GI accepts records up to the maximum string length [!New Feature!]
      GTM-8028
      -
      Other
      Encryption plugin loads correctly for UTF-8 mode processes with standard GT.M installation directory structure
      GTM-8034
      -
      Language
      On the JOB command, enable naming of both output and error when appending JOBPID [!New Feature!]
      GTM-8038
      -
      Language
      $ZCONVERT(...,"T") works in M mode
      GTM-8076
      -
      Other
      Journal Pool Recovery
      GTM-8112
      -
      Language
      Appropriate handling by the ZSYSTEM command of a very long SHELL environment variable
      GTM-8117
      -
      DB
      Better initialization vector available for encrypted databases [!New Feature!]
      GTM-8137
      -
      Admin
      Allowing more than 32Ki processes to access the database and journal pool [!New Feature!]
      GTM-8190
      -
      DB
      Optional logging of non-tp restart conflicts [!New Feature!]
      GTM-8215
      -
      Language
      $ZCONVERT() raises ICUERROR if ICU library is unavailable
      GTM-8223
      -
      Admin
      MUPIP LOAD recognizes a wider range of labels and also DOS-formated records [!New Feature!]
      GTM-8225
      -
      Admin
      GT.M uses the default zlib on AIX [!New Feature!]
      GTM-8296
      -
      Language
      Version-agnostic invocation of $ZPEEK() with ^%PEEKBYNAME wrapper [!New Feature!]
      GTM-8297
      -
      Language
      JOBLVN2LONG message contains length information
      GTM-8302
      -
      Language
      TLS Socket renegotiation and other features for server implementation [!New Feature!]
      GTM-8326
      -
      Admin
      Allow journal pool size to be greater than 2GB
      GTM-8336
      -
      DB
      Performance improvement initializing encryption for databases with multiple encrypted regions
      GTM-8340
      -
      DB
      Receiver, Update Process, and Update Writer Helper Improvements [!New Feature!]
      GTM-8342
      -
      Admin
      Better MUPIP TRIGGER delete confirmation interaction [!New Feature!]
      GTM-8352
      -
      Language
      Improved UTF-8 character handling for $EXTRACT() and $FIND() [!New Feature!]
      GTM-8361
      -
      Admin
      Reference implementation of encryption plugin included only as source code [!New Feature!]
      GTM-8389
      -
      Language
      Source references in triggers outside of explicit TP use any available cached source [!New Feature!]
      GTM-8394
      -
      Admin
      Add robustness to ROLLBACK/RECOVER for an operationally odd case
      GTM-8395
      -
      Other
      Restore patience for startup of gtmsecshr
      GTM-8397
      -
      Language
      Ensure proper delivery of any process termination messages
      GTM-8399
      -
      DB
      Better deletion of malformed trigger representations
      GTM-8403
      -
      Other
      The %MPIECE utility NEWs all local variables
      GTM-8404
      -
      Language
      Calls to $TEXT() that are known at compile time are treated as literal strings [!New Feature!]
      GTM-8407
      -
      Language
      Correct indirection for ZSHOW
      GTM-8410
      -
      Admin
      Fix Source Server journal switch race
      GTM-8416
      -
      Other
      Better alignment of $HOROLOG and journal time stamps
      GTM-8417
      -
      Language
      Fix for ZPRINT edge case involving triggers, indirection and source file instability
      GTM-8420
      -
      Admin
      See GTM-7658
      GTM-8421
      -
      Admin
      Receiver Server started with -autorollback continues when an online rollback does not change the state of the database
      GTM-8422
      -
      Admin
      See GTM-6388
      GTM-8423
      -
      Admin
      The Receiver Server appropriately handles transactions larger than 2MiB
      GTM-8425
      -
      Admin
      Fix an evil interaction between the Update Process and Online Rollback
      GTM-8428
      -
      Admin
      MUPIP INTEG correctly reports large values for things it counts
      GTM-8429
      -
      Other
      Correction to open source builds
      GTM-8431
      -
      Language
      $TEXT() accepts ^GTM$DMOD and ^GTM$CI as arguments
      GTM-8433
      -
      Language
      ZSHOW expr:gvn output format change and ^%ZSHOWVTOLCL utility [!New Feature!]
      GTM-8435
      -
      Language
      Prevent a possible hang due to an externally initiated termination
      GTM-8440
      -
      Language
      Fix to handling of over-long device names
      GTM-8441
      -
      Other
      gtminstall script qualifier fixes
      GTM-8443
      -
      Admin
      Fix epoch taper rare edge case
      GTM-8448
      -
      Language
      Better handling of MUPIP STOPs
      GTM-8450
      -
      Language
      Prevent time overflows in $ZGETJPI()
      GTM-8457
      -
      DB
      Fix for an edge case in trigger delete
      GTM-8458
      -
      Other
      Address possible mis-ordering of DSE output
      GTM-8461
      -
      Admin
      Source Server reliably updates the resync sequence number in the replication instance file
      GTM-8464
      -
      Admin
      MUPIP EXTRACT on encrypted database creates valid binary extract files regardless of mapping
      GTM-8465
      -
      Language
      JOB with PASSCURLVN appropriately handles alias containers containing KILL'd alias variables
      GTM-8468
      -
      Admin
      Improved Source Server management of journal files
      GTM-8470
      -
      Admin
      See GTM-7831
      GTM-8471
      -
      Other
      gtmsecshr does not trigger false ARCTLMAXLOW warnings
      GTM-8475
      -
      Language
      Prevent a case where $ZSEARCH() could hang indefinitely
      GTM-8476
      -
      Language
      Fix for error handling in triggers on spanning nodes or spanning regions
      GTM-8477
      -
      Language
      GT.M no longer issues an inappropriate TLVLZERO error
      GTM-8478
      -
      Admin
      "Sending REPL_RENEG_COMPLETE" in Source Server log file
      GTM-8479
      -
      Admin
      MUPIP REORG really does respond to gtm_poollimit
      GTM-8480
      -
      Admin
      Minimize size of result from MUPIP BACKUP -DATABASE [!New Feature!]
      GTM-8481
      -
      Admin
      MUPIP INTEG handles a flood of DBTNTOOLG errors from the same global correctly
      GTM-8483
      -
      Language
      MUPIP JOURNAL -EXTRACT leaves journal files in a wholesome state
      GTM-8484
      -
      Language
      M compilations, trigger compilations, and online integrity checks no longer SIG-11 in rare cases
      GTM-8485
      -
      Admin
      MUPIP JOURNAL correctly issues FILEPARSE errors for invalid paths
      GTM-8486
      -
      Language
      ZROSYNTAX errors do not cause segmentation violations
      GTM-8487
      -
      Admin
      No more inappropriate REPLINSTMATCH errors
      GTM-8489
      -
      DB
      Prevent inappropriate Source Sever termination
      GTM-8490
      -
      Language
      VIEW command does not accept 0 and 1 as arguments
      GTM-8491
      -
      Language
      Improved $ZSEARCH on AIX for non-wildcard searches
      GTM-8494
      -
      Admin
      Better maintenance of an Instance file by MUPIP BACKUP and MUPIP REPLIC
      GTM-8495
      -
      Other
      Improve DSE key interpretation of damaged blocks under some circumstances
      GTM-8499
      -
      DB
      Unusual sequence of KILLs does not result in process termination with SIG-11
      GTM-8500
      -
      DB
      Deadlock recovery for the internal locks
      GTM-8501
      -
      DB
      Fix for NOCHLEFT error during process shutdown
      GTM-8502
      -
      Admin
      MUPIP standalone commands use the same caution as MUPIP RUNDOWN [!New Feature!]
      GTM-8506
      -
      DB
      Prevent trigger problem from causing a deadlock
      GTM-8507
      -
      Admin
      Fix rare case that inappropriately terminated replication between two SI nodes
      GTM-8511
      -
      Other
      Allow DSE to map resource even if they don't match the file header
      GTM-8512
      -
      Language
      JOB command uses $zgbldir as the default value for the command parameter GBLDIR
      GTM-8514
      -
      Other
      −−xec is optional for %XCMD

    Database

    • Processes execute substantially less logic when exiting database files opened with the BG access method. Previously process exit involved more checking, which could significantly slow the exit and consume CPU resources potentially usable by other processes, behavior which was most visible when a large number of processes concurrently attempted to exit databases with large numbers of regions and large numbers of global buffers per region. (GTM-6301)

    • A process with read-only access run on an otherwise unaccessed database that was not shutdown in an orderly fashion, due to for example a kill -9, attached processes exceeding 32Ki, etc., leaves shared memory intact. Previously, such a process could cause the loss of the shared resource and, under some circumstances, updates it contained. (GTM-7608)

    • GT.M uses non-zero, context-sensitive, initialization vectors (IVs) when it encrypts or decrypts databases, journal files, binary extracts and bytestream backups; previously it used empty (all zeros or "NULL_IV") initialization vectors.

      MUPIP EXTRACT -FORMAT=BIN accepts a -NULL_IV qualifier and generates extracts in the following formats:

      • Level 6 for extracts that include no encrypted region (i.e., no data in the extract is encrypted). This is unchanged from prior releases.
      • Level 8 for extracts that include at least one encrypted region (i.e., some or all data is encrypted), and the extract was generated either (a) with the -NULL_IV flag, or (b) from database regions that are encrypted with null IVs, to generate a file with null IVs. MUPIP LOAD from GT.M V6.2-002/-002A can load level 8 extracts (but see the discussion of GTM-8360 in the V6.2-002 release notes on extracts that mixed encrypted and unencrypted regions in GT.M releases prior to V6.2-002)
      • Level 9 for extracts that include at least one encrypted region, and the extract uses IVs - i.e., MUPIP LOAD only from V6.3-000 and future releases will be able to accept this format.

      MUPIP BACKUP -BYTESTREAM in V6.3-000 uses level format 8 for an encrypted region and level format 9 for an unencrypted one (i.e., the first 5 characters of the label are "GDSV8" or "GDSV9", respectively). Bytestream backups created from a database with a particular minor version can only be restored onto a database with the same minor version. In case of a minor version mismatch GT.M issues the MUPRESTERR error with a descriptive addendum.

      Journal and database file header dumps, produced using MUPIP JOURNAL -SHOW=HEADER and DSE DUMP -FILE -ALL, respectively, report whether an all-zero IV (NULL_IV) is in use.

      Additionally, ZSHOW "D" displays the name of the encryption key and IV type for each file device that has its input, output, or both streams using encryption.

      Please note:

      • For databases created with prior versions that used an all-zero IV, GT.M continues to provide an empty IV for database blocks and journal records (see the release note for GTM-6310 on upgrading to non-zero IVs).
      • To downgrade a database that uses non-zero IVs to a database that uses zero IVs, extract the contents with MUPIP EXTRACT and use MUPIP LOAD to load the contents into a database created with a prior GT.M version that uses zero IVs. If the MUPIP LOAD targets a prior version of GT.M, the extract needs to either specify FORMAT=ZWR or FORMAT=BIN -NULL_IV.
      • While GT.M releases that provide non-zero IVs can use databases from versions of GT.M that use zero IVs, prior versions of GT.M that use zero IVs cannot process files that have non-zero IVs (e.g., while MUPIP LOAD can process binary extracts in the prior GDS level 8 format, previous GT.M versions cannot process GDS level format 9 binary extracts).

      (GTM-8117) [!New Feature!]

    • V63-000A Processes starting up with an Instance Freeze in place can proceed up to their first attempt to perform an update. Previously, if all processes accessing a database region which was a member of a frozen instance had been shut down with a SIGTERM, subsequent processes could hang attempting to connect to that database region, even if their actions did not involve updates. This issue was partially addressed in V6.3-000, but the Source Server could incorrectly rundown database regions on frozen instances, leading to the hang. (GTM-8177)

    • The gtm_nontprestart_log_delta and gtm_nontprestart_log_first environment variables control whether and how GT.M sends to the syslog NONTPRESTART messages that supply information on non-TP "mini transaction" restarts. If $gtm_nontprestart_log_delta is a non-zero integer, GT.M uses the value as a sampling interval for the messages, so a value of one (1) produces a report for every non-TP restart, a value of two (2) means a report for every other non-TP restart, etc. If $gtm_nontprestart_log_delta is defined as described and $gtm_nontprestart_log_first is also a non-zero integer, GT.M reports the first $gtm_nontprestart_log_first non-TP restarts before reporting samples as defined by $gtm_nontprestart_log_delta. Previously, GT.M did not provide detailed information for non-TP mini-transactions, but it did provide cumulative restart non-TP mini-transaction restarts using the NR0, NR1, NR2, NR3 fields in the ZSHOW "G" output. In addition, if the restart occurs due to a conflict in the global directory tree, the TPRESTART message reports "*DIR" for the glbl field. Previously, in that case, it displayed only "^" with no global variable name. TPRESTART messages include the subscript of the contested global. Previously, it reported global names without any subscript information. VIEW [NO]LOGN[ONTP][:intexpr] allows a process to dynamically change the logging to the syslog of NONTPRESTART messages established at process startup by the environment variables gtm_nontprestart_log_delta and gtm_nontprestart_log_first. VIEW "NOLOGNONTP" turns off the logging of NONTPRESTART messages to the syslog. VIEW "LOGNONTP"[:intexpr] turns on logging of NONTPRESTART messages to the syslog. If no intexpr is specified, GT.M uses the value of environment variable gtm_nontprestart_log_delta, if it is defined, and one (1) otherwise (that is, log every transaction restart). A negative value of intexpr turns off the logging of NONTPRESTART messages. Note that it is not possible to perform the operations of gtm_nontprestart_log_first with VIEW "LOGNONTP"[:intexpr]. (GTM-8190) [!New Feature!]

    • Encryption initialization is faster for databases with multiple encrypted regions, with the improvement more noticeable as the number of regions increases. To facilitate this performance improvement, GT.M requires the encryption configuration file (referred to by $gtmcrypt_config) to specifically associate the key used by each database file with that database file name, raising an error if an entry mapping the key to the file does not exist. Previously, GT.M accepted any key with a hash matching that in the database file header, even a key that was not specifically mapped to a database file name that used it. This enhancement benefits from changes to the API of the encryption plugin. (GTM-8336)

    • Update helper writer processes increase replication throughput, decrease backlog, and improve manageability:

      • Update writer helper processes start flush timers, participate in epoch tapering, and perform timed epochs. Previously writer helpers only flushed dirty blocks.
      • The Update Process no longer starts or restarts flush timers on a database if there is another process with a timer, e.g. an update writer helper. Previously the Update Process typically would establish a timer, preempting writer helpers from performing them.
      • The Receiver Server actively notifies the Update Process when there is work to be done. Previously the update process periodically polled for updates when the receive pool backlog reached zero, potentially leading to short periods where the backlog increased.
      • MUPIP REPLICATE -RECEIVER -SHUTDOWN shuts down update helper processes left running after the receiver shutdown abnormally. Previously a prior MUPIP REPLICATE -RECEIVER -SHUTDOWN -HELPERS was required to terminate each such process.

      (GTM-8340) [!New Feature!]

    • $ZTRIGGER() and MUPIP TRIGGER delete all, "-*", operations delete malformed trigger records, identifying such malformed trigger records with TRIGDEFBAD warnings. Previously trigger delete ignored some malformed triggers making them undeletable. In some cases, attempts to view (SELECT) these malformed triggers failed, making them invisible as well. The workaround was to extract all triggers to a file, add a trigger for each global variable with a trigger, followed by a delete all, "-*". This deleted all triggers and restored the desired triggers in one transaction. (GTM-8399)

    • $ZTRIGGER()and MUPIP TRIGGER appropriately delete triggers as specified; previously under rare circumstances, they silently failed to do so. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8457)

    • Processes that have read-write access to a journaled database file, but have not yet performed any updates to it (i.e., processes that have not yet opened the journal file for that database file), cooperate correctly with processes that have read-write access and have performed updates. Previously, it was possible for the former to pick up all available slots for flushing dirty buffers (the default being two slots), resulting in an out-of-design situation where dirty buffers did not get flushed in a timely manner, in turn resulting in the Source Server terminating with a SEQNUMSEARCHTIMEOUT error. Additionally, the Source Server issues an alert every 50 seconds (instead of 10 seconds previously). (GTM-8489)

    • KILL of a global outside of a TP transaction following a large TP transaction with certain characteristics by the same process works correctly; previously this unusual sequence could terminate a process with a segmentation violation (SIG-11). Database structural integrity was not at risk from this behavior. (GTM-8499)

    • GT.M does not internally deadlock in the presence of certain rare, asynchronous events, as it previously could in releases V6.0-003 through V6.2-002A. This issue was only observed in the GT.M development environment, and was never reported by a user. Note that the design of GT.M precludes deadlocks in normal usage. (GTM-8500)

    • MUPIP, LKE, and DSE no longer issue NOCHLEFT fatal errors while handling errors in database disconnect which occur during process shutdown. (GTM-8501)

    • GT.M processes no longer deadlock when a trigger causes a fatal error, under certain unusual conditions. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8506)

    • V63-000A TP transactions work appropriately for MM access databases when there is a concurrent database file extension. Previously, in rare cases these circumstances caused GT.M to terminate with a segmentation violation (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8523)

    • V63-000A GT.M issues a JNLPOOLSETUP error if/when 32Ki processes open the journal pool and the corresponding replication instance file does not have -qdbrundown enabled. In GT.M V6.3-000, the GT.M process used to terminate abnormally with a SIG-11 while trying to issue the error. (GTM-8535)

    • V63-000A Replication works correctly when the replication instance file has -qdbrundown enabled and some processes in the instance have read-only access to the replication instance file. In V6.3-000, if the 32,768th process accessing the instance had read-only access to the replication instance file, it would issue a REPLINSTOPEN error, and hold internal locks on the Journal Pool and instance file, resulting in hangs and MUTEXLCKALERT messages from other processes. A value of 1 returned by $$^%PEEKBYNAME("node_local.ftok_counter_halted",region) means that the number of processes accessing the region ever reached 32,768, resulting in the counter no longer being maintained. Similarly, a value of 1 returned by $$^%PEEKBYNAME("jnlpool_ctl_struct.ftok_counter_halted") means that the number of processes attaching to the Journal Pool reached 32.768, again resulting in the counter no longer being maintained. A value of TRUE in the "CTL FTOK Counter Halted" field of the output from MUPIP REPLIC -SOURCE -JNLPOOL -SHOW also shows the Journal Pool information. DSE and LKE now send any RESRCWAIT messages to the syslog. Previously, they used to display such messages in their output. (GTM-8538)

    • V63-000A With epoch tapering enabled, GT.M issues a single fsync in preparation for an epoch; previously it could issue a number of fsyncs prior to the epoch. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8539)

    • V63-000A LOCK (and ZALLOCATE) issue a LOCKTIMINGINTP warning message to the syslog when a process fails to acquire a LOCK within a critical resource holding retry of a TP transaction. Unlike TPNOTACID warnings, which signal the release of critical resource, LOCKTIMINGINTP does not indicate a release of resources. Such a LOCK must have a timeout less than gtm_tpnotacidtime, or, if undefined, its default of two (2) seconds, which should limit the duration of the resource blockage it causes; a timeout of 0 (zero) prevents this warning. Note that FIS recommends avoiding the use of LOCK commands within TP transactions. Previously, the described condition produced a TPNOTACID warning with its accompanying release of resources, which made the transaction more likely to make repeated restarts. (GTM-8546)

    • V63-000A GT.M avoids holding a critical shared resource on database regions and the journal pool longer than necessary. Previously, a non-TP transaction on a replicated region which processed a timed epoch would hold the resource on the journal pool while processing the epoch, and a process in the final retry of a transaction could frequently sleep or yield the processor, potentially repeatedly, while holding the resource on the database region. (GTM-8554)

    Language

    • V63-000A GT.M is silent about implicitly assigning the current global directory to a value that identifies an inaccessible file. Note that attempting to use such a value for a global directory continues to produce a ZGBLDIRACC error. Previously, with such a $ZGBLDIR value, a QUIT after a NEW $ZGBLDIR resulted in a STACKOFLOW error and a valid external reference produced an inappropriate ZGBLDIRACC error. (GTM-4759)

    • ZMESSAGE accepts an indirect argument. Previously this syntax produced a GTMASSERT. (GTM-6114)

    • In an M mode process, a WRITE to a sequential device after a SET $X to a value greater than the device WIDTH or a reduction in WIDTH to less than the current $X acts as if the first character caused $X to exceed the WIDTH inducing an immediate WRAP, if WRAP is enabled. Previously, $X exceeding WIDTH in an M mode process caused a SYSTEM-E-ENO14, Bad address error. (GTM-7060) [!New Feature!]

    • $ZWRITE() accepts a second intexpr which specifies the direction of the conversion. No value or a zero value converts the first argument to ZWRITE format and a non-zero value converts the first argument from ZWRITE format to a string with embedded non-graphic characters. In addition, $ZWRITE() now takes the cannonical or non-cannonical nature of its first argument into account; previously it attempted to treat non-canonical numeric values as numbers rather than strings, which caused errors and inappropriate results. Also if all its arguments are literals, $ZWRITE() evaluates to a literal constant at compile time. Previously $ZWRITE only accepted a single argument, converting only to ZWRITE format, and always evaluated at run time. (GTM-7604) [!New Feature!]

    • The GT.M compiler resolves some expressions involving string literals at compile time, reducing both code size and run time CPU requirements. Currently the compiler does this for concatenation operations, $[Z]ASCII(), $[Z]EXTRACT(), $[Z]PIECE(), and $ZSUBSTR(). For code compiled in UTF-8 mode, this means that the compiler can report BADCHAR warnings for strings that are not legal UTF-8 strings, where previously it did not. The compiler flags these as warnings, rather than as errors, since the possible difference between the compile time and run time setting of [NO]BADCHAR dictates that the compiler cannot with certainty determine whether strings containing illegal UTF-8 characters are actually errors (for example, they may contain binary data). When the compiler reports BADCHAR warnings, it defers the computation to run time, instead of attempting to precompute the result. Note that sometimes a single character with an invalid encoding can cause multiple warnings, for example, when a string that is not a valid UTF-8 string appears inside a function such as $PIECE(). Regardless of any compile time warnings, there is no change to run time functionality of any M application code as a result of this change. (GTM-7762) [!New Feature!]

    • Using VIEW "JOBPID":1 does not issue an error when the JOB command parameters ERROR and OUTPUT point to the same file; previously, while the effect of the VIEW command was not documented, using the same file name for ERROR and OUTPUT and VIEW "JOBPID":1 resulted in an error. (GTM-8034) [!New Feature!]

    • $ZCONVERT(...,"T") works in M mode; previously it only worked in UTF-8 mode. (GTM-8038)

    • Processes no longer terminate with a segmentation violation (SIG-11) when:

      • executing the ZSYSTEM command with an overly long value of the environment variable SHELL; and

      • initializing the reference implementation of the encryption plugin with an overly long value of the environment variable GNUPGHOME.

      These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8112)

    • $ZCONVERT() raises an ICUERROR if GT.M is unable to correctly access the ICU library; previously the process terminated with a GTMASSERT. It also runs faster than it did previously. (GTM-8215)

    • %PEEKBYNAME() provides a stable interface to $ZPEEK() that uses control structure field mnemonics. $ZPEEK() provides a read-only mechanism to access selected fields in selected control structures in the address space of a process, including process private memory, database shared memory segments and Journal Pools. Although application code can call $ZPEEK() directly, such direct access must use numeric arguments that can vary from release to release. Access using %PEEKBYNAME makes application code more stable across GT.M releases. For more information, refer to Additional Information forGTM-8296- %PEEKBYNAME(). (GTM-8296) [!New Feature!]

    • If the JOB command finds the ZWRITE representation of an lvn consisting of a its full name, its subscripts, corresponding value, quotes and the "=" sign, exceeding 1MiB, it produces a JOBLVN2LONG error in both JOB'ing and JOB'd process' error stream. This message includes the attempted length and maximum limit. Previously, the JOB'ing process would issue a JOBLVN2LONG error without the lvn length details, and JOB'd process would issue a JOBLVNDETAIL with the length information which the JOBLVN2LONG currently displays. (GTM-8297)

    • The WRITE /TLS("renegotiate"[,,[tlsid][,,options]]) command on a server socket allows applications to request a TLS renegotiation. In the command:

      • The second and fourth arguments are unspecified.

      • tlsid refers to the name of a section in the configuration file specified by the gtmcrypt_config environment variable. If tlsid is not specified, GT.M creates a virtual section by appending "-RENEGOTIATE" to the tlsid used to enable TLS on the socket. If no section named tlsid is present in the configuration file, GT.M creates a virtual section with that name for the life of the process.

      • Supported configuration file options passed in the command are (case-sensitive): verify-depth, verify-level, verify-mode, session-id-hex, and CAfile.

      • When tlsid is specified, any options in the command take precedence over options of the same name specified in the configuration file section.

      The WRITE /TLS("renegotiate",...) command ignores options other than those listed above. The options remain in effect for the socket after the renegotiation. Any virtual section remains available in the current process.

      Renegotiation requires the suspension of application communication and the application must read all pending data before initiating a renegotiation. This means that in the communication protocol used, both parties must be at a known state when renegotiating keys. For example, in GT.M replication, one party sends a renegotiation request and waits for an acknowledgement before initiating the renegotiation.

      The configuration file can specify options, although the WRITE /TLS("renegotiate",...) command can override them. Note that configuration file options may be useful even without the renegotiate command.

      • The CAfile option when specified for a server connection either in a tlsid level configuration file section or for the renegotiate command allows the server to inform the client of acceptable certificate authorities via the OpenSSL function SSL_set_client_CA_list(). The determinant definition for the acceptable list of certificate authorities sent to the client comes in descending order of priority from the one specified by the WRITE /TLS("renegotiate",...) command, the one specified by the CAfile value in the tlsid section used to establish the TLS connection, and finally that specified at the tls level.

      • The verify-level option takes a string value to specify any additional certificate verification in addition to the basic OpenSSL verification. The only value currently accepted is "CHECK" which requests additional checks on the results of the basic OpenSSL certificate verification. A leading exclamation mark ("!") disables a verify-level option. The verify-level options specified at lower levels are merged with those options already specified at higher levels. CHECK is enabled by default for all TLS connections.

      • The session-id-hex option takes a string value which is used to set the SSL session_id context for server sockets, which may be specified in the tlsid section of a config file or on WRITE /TLS("RENEGOTIATE",...). See the OpenSSL man page for SSL_set_session_id_context for usage details. The value should consist of hexadecimal digits representing the desired value. Application code can call the %UTF2HEX utility routine to translate a character string to the corresponding string of hexadecimal digits. If neither the command or the associated tlsid section in the configuration file specify a session-id-hex option when creating the socket, GT.M uses the current tlsid, translated into hexadecimal digits.

      The default for the configuration file option verify-mode is SSL_VERIFY_PEER. Previously it was SSL_VERIFY_NONE for TLS enabled sockets.

      Including "SESSION" in the fourth argument of $ZSOCKET "TLS" returns information related to SSL sessions including information about renegotiations. The following is an example of the information returned in addition to the information previously returned:

      |S:RENSEC:1,RENTOT:1,SESSID:A9EB18B4731B2E4ABA572C8386213
+4C67C9561597D5FAF47CDD5B866B77215FF,SESEXP:Thu Jun  4 21:07:11 2015

      where "|S:" denotes this piece contains session information, "RENSEC:" indicates whether secure renegotiation is available (1) or not (0), "RENTOT:" gives the current total number of renegotiations done on this socket, "SESSID:" shows the session id in hexadecimal, and "SESEXP:" indicates when the session expires in the local timezone.

      Including "OPTIONS" in the fourth argument of $ZSOCKET "TLS" now returns the verify mode after the TLS options (that is, "|O:hexdigits") as a comma and two hexadecimal digits. The verify mode values are defined in openssl/ssl.h.

      Including "ALL" in the fourth argument of $ZSOCKET "TLS" returns all available information.

      A successful WRITE for a TLS enabled socket with an argument larger than the ZBFSIZE for the socket is not considered an error. Previously, such a WRITE indicated an error with the following $DEVICE value: "1,Unknown error -1" or if IOERROR="TRAP", $ZSTATUS included:

      %GTM-E-SOCKWRITE, Write to a socket failed,%GTM-I-TEXT, Unknown error -1

      (GTM-8302) [!New Feature!]

    • To improve performance of certain UTF-8 string functions, when a string 32-bytes or longer is passed as the first parameter to $EXTRACT() and $FIND() calls that have three parameters, GT.M caches information regarding transitions between blocks of ASCII characters ($CHAR(0) through $CHAR(127)) and non-ASCII UTF-8 characters ($CHAR(128) & up). Actual improvement in application performance can range from unobservable to dramatic depending on the prevalence of this use case. As there are a couple of tuning parameters for this optimization (with defaults that are reasonable in our judgement), if you have code that benefits from this optimization, please contact your GT.M support channel for help in experimenting with the tuning the parameters. (GTM-8352) [!New Feature!]

    • When a process accesses a trigger definition with ZPRINT or $TEXT() outside of a TP transaction and it has previously fetched the definition with no intervening execution of a revised trigger definition, GT.M returns information cached by that prior access. Previously, if another process had deleted or modified the definition after its last source access and with no intervening execution, ZPRINT gave a TRIGNAMF error and $TEXT() returned an empty string. Note that accessing the source code within a TP transaction (either implicit or explicit) always uses the current definition. (GTM-8389) [!New Feature!]

    • When interrupted by a signal requesting termination, such as SIGTERM, while writing to the principal device, GT.M prints that all subsequent rundown messages correctly. Previously, there was a small window in writing to the principal device when an external signal could result in corrupt rundown messages. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8397)

    • Calls to $TEXT() for which the compiler can determine the source code line at compile time it compiles as literal strings in the object code. Specifically, this optimization occurs when the entryref refers to a line in the current routine, and no component of the entryref uses indirection. (GTM-8404) [!New Feature!]

    • ZSHOW accepts atomic indirection in the second expression of its argument. Previously it incorrectly gave an error for such an attempt. (GTM-8407)

    • ZPRINT handles an unusual case when it appears within trigger code and also within an XECUTE or indirection and the target routine has become empty (has zero length). Previously, such circumstances intermittently produced a ZLINKFILE error. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8417)

    • $TEXT() returns the empty string for ^GTM$DMOD and ^GTM$CI; previously these $TEXT() arguments, which represent respectively the base frames for mumps -direct and a call-in and could be derived from $STACK(), $ZPOSITION or ZSHOW "S", produced an RPARENMISSING error. (GTM-8431)

    • ZSHOW expr:gvn stores continuations of information that do not fit in the maximum record size as immediate descendants, using ordinal subscripts starting at one (1), of the node holding the beginning of the information. This facilitates identifying when multiple nodes need to be reassembled to find the entire item. In addition, the ^%ZSHOWVTOLCL utility program restores ZSHOW "V":gvn data into its original local variables. The utility needs to be invoked with $ECODE set to the empty string ("") and cannot restore a local variable with the same name (%ZSHOWvbase) as the parameter in its formal list. Other ZSHOW information typically fits within common database record size limitations. Previously, ZSHOW expr:gvn stored continuation nodes at the same level as other nodes. Although this change is not backward compatible, it facilitates automated restoration even of nodes exceeding the maximum record size of the global, which was not the case previously (GTM-8433) [!New Feature!]

    • When a GT.M process receives a MUPIP STOP while doing a READ on a SEQUENTIAL, FIFO, or PIPE device in NOFIXED, M mode, the process terminates. Previously, this combination could cause the process to hang. (GTM-8435)

    • GT.M produces an appropriate error for an inappropriately long device name in the argument of OPEN, USE and CLOSE commands; previously such an argument could cause a segmentation violation (SIG-11). (GTM-8440)

    • When interrupted by a signal requesting termination, such as SIGTERM GT.M handles the termination appropriately. In GT.M V6.2-002 and V6.2-002A, if the interrupt happened during certain small windows of execution, it was possible for the process to terminate abnormally, hang, or exhibit other incorrect behavior under rare conditions. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8448)

    • $ZGETJPI() reports large values appropriately; previously large times could wrap. (GTM-8450)

    • V63-000A ZWRITE and ZSHOW "V" work appropriately after an interrupted MERGE command involving a local variable; previously this combination could cause a segmentation violation (SIG-11). (GTM-8454)

    • A JOB command with PASSCURLVN correctly passes alias containers that contain KILL'ed original aliases. Previously, JOB command with PASSCURLVN could fail with INDEXTRACHARS error in such a case. (GTM-8465)

    • $ZSEARCH() avoids a possible deadlock that could cause a process to hang indefinitely. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8475)

    • GT.M handles errors from triggers on globals that span nodes or regions when the error handler does not clear $ECODE. Previously, when a trigger's error handler did not clear $ECODE for an update to a global that spanned regions or nodes, GT.M issued a fatal GTMASSERT2 error. (GTM-8476)

    • GT.M no longer issues an inappropriate TLVLZERO error when executing a TCOMMIT command, as it previously did under certain very rare conditions. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8477)

    • MUPIP JOURNAL -EXTRACT leaves journal files in a wholesome state when run where a corresponding database was not shutdown in an orderly fashion, due to for example a kill -9, attached processes exceeding 32Ki, etc. Previously, under these somewhat unusual conditions MUPIP JOURNAL -EXTRACT left the journal files in a state where they could not be applied to recover the database. (GTM-8483)

    • M compilations, trigger compilations, and online integrity checks no longer result in segmentation faults (SIG-11) in rare cases. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8484)

    • GT.M correctly issues a ZROSYNTAX error when transitioning from a $ZROutines with auto-relink enabled to a $ZROutines that has non-existent directory paths. Previously, GT.M terminated with a segmentation violation (SIG-11). (GTM-8486)

    • GT.M treats VIEW 1 and VIEW 0 as errors. Previously, it treated these constructs as VIEW "GDSCERT":1 and VIEW "GDSCERT":0 commands respectively. (GTM-8490)

    • On AIX, for non-wildcard searches, $ZSEARCH() exhibits performance similar to that of other platforms. The correction made with GTM-8237 in V6.2-002 exposed decreased and erratic performance on AIX of the POSIX service used to perform such searches. [AIX] (GTM-8491)

    • Unless overridden with a GBLDIR jobparameter, processes started with the JOB command use the global directory specified by the $ZGBLDIR of the process executing the JOB command (as documented). Previously, these processes incorrectly used the value of the environment variable gtmgbldir in the environment of the parent executing the JOB command. As a side effect, since the process executing the JOB command would have previously validated the path to the global directory, a JOB'd processes does not terminate with a segmentation violation (SIG-11), as it previously did, if $gtmgbldir is longer than GT.M's limit of 255 bytes for the path to the global directory. You should check all occurrences in your application where it executes JOB commands without GBLDIR jobparameters when its values of $ZGBLDIR and $gtmgbldir differ. In addition, processes no longer terminate with a segmentation violation (SIG-11) when: executing the ZSYSTEM command with an overly long value of the environment variable SHELL; and initializing the reference implementation of the encryption plugin with an overly long value of the environment variable GNUPGHOME. These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8512)

    • V63-000A GT.M correctly handles pattern specifications where the pattern contains a finite pattern atom (for example 1A) followed by an infinite pattern atom with a pattern code that is a superset of the first pattern (for example .AN) and followed by an alternation (for example .(1".")). Previously it used to treat the finite pattern atom in the above specification as infinite and incorrectly merge the two treating a 1A.AN.(1".") as .AN.(1".") resulting in incorrect results. In addition, the pattern match operator run- time performance has been improved for various types of pattern expressions. (GTM-8522)

    • V63-000A If the SHELL environment variable is undefined at GT.M process start-up or if an external call unsets the SHELL enviroment variable, the ZSYSTEM command uses /bin/sh to execute the shell command. Previously, if the SHELL environment variable was undefined at GT.M process start-up, the ZSYSTEM command would fail to work, issuing a "not found" error. In GT.M V6.3-000, if an external call unset the SHELL environment variable, only the first ZSYSTEM call worked as intended. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8530)

    • V63-000A Intrinsic functions that use integer or numeric arguments actually constructed using compile-time optimizations to resolve expressions consisting entirely of literals for concatenation and some string functions in source code work as documented. For example $ORDER(xxx,"-"_"1"), where xxx is any legal first argument produced a GTM-E-ORDER2 error. Not invoking the optimization by avoiding the concatenation worked correctly - e.g., $ORDER(xxx,"-1") - as did any operation that coerced the result to numeric - e.g., $ORDER(xxx,"-"_"1"+0). Owing to a problem with string optimizations (GTM-7762 and GTM-8404) in V6.3-000 this described combination of factors generated inappropriate errors. (GTM-8540)

    • V63-000A $TEXT(x) where x is a label works correctly when there is a label xyz in the current routine (a) preceding label x and (b) where x is a leading substring of xyz. Note that $TEXT(x^routine) was not affected. Note also that "local labels," those terminated with a colon (:), are accessible at compile time, but not at run time. Owing to a bug with optimization GTM-8404 in V6.3-000, $TEXT(x) would, under these circumstances, incorrectly provide the source code $TEXT(xyz). If there were multiple labels xyz1, xyz2, etc., $TEXT(x) would provide the source code for the first, i.e., $TEXT(xyz1). (GTM-8549)

    • V63-000A When assigned to a local variable node, the result of $FNUMBER() where the second argument is the empty string and the third argument specifies potential rounding retains the value assigned. Previously in such circumstances, GT.M could subsequently alter the value in such a node to an incorrect value. The workaround was to use $JUSTIFY(x,0,n) rather than $FNUMBER(x,"",n)(GTM-8558)

    System Administration

    • MUPIP JOURNAL commands (e.g. ROLLBACK, RECOVER, VERIFY, SHOW etc.) accept the -PARA[LLEL][=n] qualifier to specify the number of parallel threads (for backward processing) and parallel processes (for forward processing). Omitting the qualifier or specifying a value of one (1) defaults to a single process with no threads. Omitting the value or specifying a value of zero (0) specifies one thread or process per region. A value greater than one (1) specifies the maximum number of concurrent threads or processes MUPIP should use, although it never uses more than one per region. If the number of regions exceeds the specified value, MUPIP allocates threads or processes in an order determined by timestamps in the journal records. The environment variable gtm_mupjnl_parallel provides a value when the command has no explicit -PARALLEL qualifier; when defined with no value gtm_mupjnl_parallel acts like -PARALLEL with no value. When the -PARALLEL qualifier (or the gtm_mupjnl_parallel environment variable) specifies the use of parallel processes in the forward phase of a MUPIP JOURNAL command, MUPIP may create temporary shared memory segments and/or extract files (corresponding to -extract or -losttrans or -brokentrans qualifiers) and clean these up at the end of the command; however an abnormal termination such as a kill -9 might cause these to be orphaned.

      Journal extract files (created by specifying one of -extract or -brokentrans or -losttrans to a MUPIP JOURNAL command) contain journal records sorted by sequence number (token_seq/jsnum) then by update order (updnum) for all regions which were replicated/journaled - in other words: in the exact order their corresponding updates happened in time. In prior versions of GT.M, these files were not sorted which meant applying lost transaction files (for example) required first sorting the file to correspond to the update-order before applying them.

      In addition, a MUPIP JOURNAL -SHOW=HEADER has default of -NOVERIFY if no other action qualifiers (-EXTRACT, -RECOVER, -ROLLBACK, -SHOW) are specified. This speeds up the command in the default case (no verification of the entire journal file occurs). Note that specifying -VERIFY explicitly still does the verification as requested. (GTM-5007) [!New Feature!]

    • See GTM-7768. (GTM-5726)

    • With the -ENCRYPT flag, MUPIP REORG changes the encryption key of a database, or encrypts an unencrypted database, while the database continues to be used by applications. Whether or not the prior encryption uses non-zero initialization vectors (IVs), database blocks encrypted with the new key use non-zero IVs (see GTM-8117). The syntax is:

           MUPIP REORG -ENCR[YPT]=<key> -REGION <region-list>

      where <key> is a key provided by MUPIP to the encryption plugin. The reference implementation of the plugin expects a key with the specified name in the encryption configuration file identified by $gtmcrypt_config. The configuration file must contain an entry in the database section for each database file mapping to a region specified in <region-list> that names the specified key as its key. The -ENCRYPT flag is incompatible with all other command line flags of MUPIP REORG, and performs no operation other than changing the encryption key. If the specified key is already the encryption key of a database region, MUPIP REORG -ENCRYPT moves on the next region after displaying a message (on stderr, where MUPIP operations send their output).

      As MUPIP REORG -ENCRYPT must read, re-encrypt, and write every encrypted block in each database file, its operation will take a material amount of time on the databases of typical applications, and furthermore will add an additional IO load to the system on which it runs. You can use the environment variable gtm_poollimit to ameliorate, but not eliminate, the impact, at the cost of extending execution times. To minimize impact on production instances, FIS recommends running this operation on replicating secondary instances, rather than on originating primary instances.

      MUPIP REORG -ENCRYPT switches the journal file for each database region when it begins operating on it, and again when it completes, and also records messages in the syslog for both events. Note that the detailed journal extract format is now level 8.

      As is the case under normal operation when MUPIP REORG -ENCRYPT is not active, journaled databases are protected against system crashes when MUPIP REORG -ENCRYPT is in operation: MUPIP JOURNAL ROLLBACK / RECOVER recovers journaled database regions (databases that use NOBEFORE journaling continue to require FORWARD RECOVER / ROLLBACK).

      Since a database file utilizes two keys while MUPIP REORG -ENCRYPT is underway, the database section of the configuration file provides for a single database file entry to specify multiple keys. For example, if the keys of database regions CUST and HIST, mapping to database files cust.dat and hist.dat in directory /var/myApp/prod, are to be changed from key1 to key2 using the command:

           MUPIP REORG -ENCRYPT=key2 -REGION CUST,HIST
@@ -327,7 +327,7 @@ tar -xvf source.tar

    • Follow the instructions in MUPIP SET -NOENCRYPTABLE -REGION <region-list>

      The above command also requires standalone access, and the result depends on the state of the database. It:

      • is a no-op if the database is encrypted;
      • is disallowed if the database is partially (re)encrypted; and
      • prohibits encryption if the database is not encrypted.

      Under normal operation, a database file has only one key. Upon starting a MUPIP REORG -ENCRYPT to change the key, there are two keys, both of whose hashes GT.M stores in the database file header. With a MUPIP REORG -ENCRYPT operation underway to change the key, normal database operation can continue, except for another MUPIP REORG -ENCRYPT or MUPIP EXTRACT in binary format. Other MUPIP operations, such as MUPIP BACKUP and MUPIP EXTRACT in ZWR format can occur. A MUPIP REORG -ENCRYPT operation can resume after an interruption, either unintentional, such as after a system crash and recovery, or intentional, after an explicit MUPIP STOP of the MUPIP REORG -ENCRYPT process. To resume the REORG operation, reissue the original command, including the key parameter. (Note that supplying a key other than the one used in the original command results in an error.)

      After the MUPIP REORG -ENCRYPT process completes, subsequent MUPIP REORG -ENCRYPT operations on the same region(s) are disallowed until the following command is run:

           MUPIP SET -ENCRYPTIONCOMPLETE -REGION <region-list>
-

      The reason to block subsequent MUPIP REORG -ENCRYPT operations upon completion of one is to provide time for a backup of the entire database before enabling further key changes. MUPIP SET -ENCRYPTIONCOMPLETE reports an error for any database region for which MUPIP REORG -ENCRYPT has not completed.

      The above changes necessitated certain alterations of the encryption plugin API (for other API changes, see GTM-8336).

      (GTM-6310) [!New Feature!]

    • See GTM-8137. (GTM-6317)

    • MUPIP EXTRACT and MUPIP JOURNAL -EXTRACT are faster. While improvements you see will depend on the circumstances of your configuration and environment, in testing in the GT.M development environment, GO and ZWR formatted extracts completed in as much as three to four times faster than before. (GTM-6388)

    • On AIX, GT.M uses the AIX provided ICU libraries when gtm_icu_version is not defined. Previously GT.M required users to build the ICU libraries. [AIX] (GTM-6858) [!New Feature!]

    • With the -ZEROBACKLOG qualifier, a MUPIP REPLICATE -SOURCE -SHUTDOWN command shuts down the Source Server either when the backlog goes to zero, or the timeout expires, whichever occurs first. (GTM-6928) [!New Feature!]

    • MUPIP JOURNAL -ROLLBACK recognizes the -FORWARD qualifier to specify it apply update records in journal files to backed up copies of database files in order to bring them to the same state that MUPIP JOURNAL -ROLLBACK -BACKWARD "*" would bring crashed database files. Unlike MUPIP JOURNAL -ROLLBACK -BACKWARD, MUPIP JOURNAL -ROLLBACK -FORWARD accepts either a comma-delimited list of region names or "*", indicating the journal files associated with all regions in the current Global Directory. A MUPIP JOURNAL -ROLLBACK -FORWARD "*" command does what a MUPIP JOURNAL -RECOVER -FORWARD "*" would do except that the -ROLLBACK also updates sequence number related fields in the database file header, and ensures update serialization across regions - MUPIP JOURNAL -RECOVER can leave one database region ahead of another region and cannot ensure database Consistency across regions, whereas MUPIP JOURNAL -ROLLBACK can ensure Consistency. Databases recovered with MUPIP JOURNAL -ROLLBACK can therefore be used in replicated instances. Note that, in the context of -RECOVER and -ROLLBACK, the "*" indicates the use of all the appropriate journal files in all the replicated regions and the quotes prevent inappropriate expansion by the OS shell. MUPIP JOURNAL -ROLLBACK -FORWARD leaves the journaling state turned off in database files (as does MUPIP JOURNAL -RECOVER -FORWARD), which in turn means that replication is also turned off; journaling should be re-enabled, and replication turned on, before database files are used in environments where they can be updated, but can be left off if subsequent access is read-only. After a MUPIP JOURNAL -ROLLBACK -FORWARD, the replication instance file needs to be recreated as part of turning replication on in the recovered database. MUPIP JOURNAL -ROLLBACK -FORWARD can use both before-image and nobefore-image journal files. See the More Information section for details on qualifier use. In addition, MUPIP JOURNAL -ROLLBACK -BACKWARD output always includes the RLBKJNSEQ message; previously the output only included this if the rollback changed the database (i.e., the operation was not a no-op). Also, MUPIP JOURNAL -RECOVER -BACKWARD -BEFORE works even when -SINCE is not specified; previously such a command terminated with a JNLTMQUAL1 error. For more information, refer to Additional Information for GTM-7291 - MUPIP JOURNAL -ROLLBACK qualifiers. (GTM-7291) [!New Feature!]

    • GT.M accepts all ICU versions reported by "icu-config -version" for gtm_icu_version. Previously GT.M required the format of gtm_icu_version to be <ICU Major Version> "." <ICU Minor Version> with no trailing digits, and required ICU versions 49 & higher (i.e., with the new ICU numbering scheme) to be specified as 4.9, 5.0, etc. (GTM-7375) [!New Feature!]

    • An improvement in database replication communication between Source and Receiver Servers reduces delays. Previously, a busy Source Server, for example, one searching through journal files to find the transaction at which to resume communication with a replicating secondary instance with a large backlog, could ignore communications long enough for the Receiver Server to close the connection and begin a reconnection cycle, adding to the persistence of the backlog. Note that a Source Server started with -JNLFILEONLY always reads from the journal files. (GTM-5726) (GTM-7768)

    • MUPIP SET recognizes the -SPIN_SLEEP_LIMIT=n where n is decimal maximum number rounded up to the nearest power of two and turned into a hexadecimal mask that determines the maximum number of nanoseconds for processes to sleep while waiting to obtain critical sections for shared resources, principally those involving databases. The default is zero (0) which causes the process to return control to the UNIX kernel to be rescheduled with no explicit delay. When the value is non-zero, the process waits for a random value between zero (0) and the maximum value permitted by the mask. DSE CHANGE -FILEHEADER -SPIN_SLEEP_MASK provides a means to directly set the hexadecimal value of the mask, which appears in DSE DUMP -FILEHEADER output with the label "Spin sleep time mask." Previously, processes always rescheduled themselves with no delay. In addition, MUPIP SET (and DSE) accept a 0 value for -SLEEP_SPIN_COUNT, which eliminates the sleep loop in the mutual exclusion (mutex) facility so processes go straight from a hard spin to a queued wait. Previously, the -SLEEP_SPIN_COUNT qualifier was not recognized by MUPIP SET and processes that exhausted the hard spin count always did at least one (1) rescheduling operation. Except on the advice of your GT.M support channel, FIS recommends leaving the default values unchanged in production environments, until you have data from testing and benchmarking that demonstrates a benefit from a change. If none of its qualifiers are out of the range from minimum to maximum, MUPIP SET processes all qualifiers for each region applying them only if all are appropriate for the region and otherwise warning of any issues. Previously, MUPIP SET stopped at the first error and if some qualifiers required standalone access and others did not, applied only those requiring standalone access and silently ignored those that did not. If you have scripting that checks for correct completion of a MUPIP SET command, no changes are required to accommodate this change. However, if your scripting checks for and takes actions based on errors reported by MUPIP SET, you should test your script and revise it as needed. (GTM-7809) [!New Feature!]

    • MUPIP JOURNAL ROLLBACK fixes DBDANGER situations and therefore neither issues DBDANGER messages to syslog nor freezes an instance. Previously, MUPIP JOURNAL ROLLBACK could send DBDANGER messages to syslog even though it would fix the problem, and, when using the Instance Freeze facility with a DBDANGER in the custom errors file, a ROLLBACK issuing a DBDANGER message would freeze until manually unfrozen. (GTM-7831)

    • GT.M replication uses the operating system and network to perform flow control. Previously, the Source and Receiver Servers performed flow control, as a consequence of which the Receiver Server could flood the socket connection with flow control messages, leading to a large number of log messages and an occasional hang in replication processing. (GTM-7838)

    • MUPIP LOAD accepts negative values in ZWR format input such as that produced by %GO. Previously, such a value caused a LOADFILERR. The workaround was to use GO format or edit the file to add a pair of double-quotes around the negative value. (GTM-8020)

    • GT.M can be configured to permit more than 32,767 processes to concurrently access a database file. In a replicated environment, to permit one or more database files to be concurrently accessed by more than 32,767 updating processes also requires the replication instance file to be configured to permit concurrent access by more than 32,767 processes. The default behavior is to limit the number of processes accessing a database file or instance file to 32,767. This permission is effected by the QDBRUNDOWN flags in database file headers and in replication instance files. When an open database file or replication instance file with QDBRUNDOWN set is first concurrently accessed by more than 32,767 processes, GT.M (a) logs a NOMORESEMCNT message in the system log, and (b) stops counting the number of attached processes. This means that GT.M cannot recognize when the number of attached processes reaches zero (0) in order to release the corresponding shared resources, and therefore requires explicit manual clean up of resources for an orderly shutdown. Previously, exceeding 32Ki attachments to shared resources caused a DBFILERR, CRITSEMFAIL error with an ERANGE status for database and replication instance files, as it still does when QDBRUNDOWN is not set.

      Except in application configurations that require it, FIS recommends not setting QDBRUNDOWN. Not setting QDBRUNDOWN allows GT.M to clean up resources, instead of putting the burden on the operational procedures. Where GT.M cannot perform an orderly shutdown, an explicit, clean shutdown must be performed as follows:

      • Replicated instances require a MUPIP JOURNAL -ROLLBACK -BACKWARD "*" executed after the MUPIP REPLICATE SOURCE -SHUTDOWN command (remember that even instances receiving a replication stream have one or more Source Servers).
      • Database files that are journaled but not part of a replication instance require a MUPIP JOURNAL -RECOVER -BACKWARD command.
      • Database files that are not journaled (and hence not replicated) require a MUPIP RUNDOWN command.

      MUPIP REPLICATE -INSTANCE_CREATE -[NO]QDBRUNDOWN controls the QDBRUNDOWN setting of a replication instance file when it is created. For an existing replication instance file, requiring stand-alone access (i.e., the instance must not have an existing Journal Pool), MUPIP REPLICATE -EDITINSTANCE -[NO]QDBRUNDOWN controls the QDBRUNDOWN setting. Specifying -QDBRUNDOWN turns it ON, and -NOQDBRUNDOWN turns it OFF. MUPIP REPLICATE -EDITINSTANCE -SHOW displays the current QDBRUNDOWN setting of an instance file as "HDR Quick database rundown is active", reported as TRUE or FALSE. Note that QDBRUNDOWN is an existing setting in database files. See the release note for GTM-8296 on accessing the QDBRUNDOWN setting using %PEEKBYNAME().

      In support of this enhancement:

      • As all processes must use the same setting of QDBRUNDOWN, changing the QDBRUNDOWN setting requires standalone access; previously it did not for database files, and was not meaningful for replication instance files.
      • MUPIP RUNDOWN issues a DBRDONLY error if it encounters a database file with read-only permissions (no read-write permission) and the database shared memory indicates that the number of attached processes exceeded 32Ki at some point after it was opened. Databases that exceed the 32Ki counter need a process with read-write ability to perform the required rundown/recover/rollback.

      The work to develop this enhancement also addressed several issues. These issues were only observed in the GT.M development environment, and were never reported by a user.

      • Endian conversion works correctly in the rare case that the database is opened by a process after MUPIP ENDIANCVT starts converting the endianness of a database, and before it blocks other processes from opening the database. Previously, this could result in a database with structural damage requiring manual repair.
      • MUPIP JOURNAL -SHOW=HEADER on a journal file of a supplementary instance reports correct stream sequence numbers (displayed as "Stream i : Start RegSeqno" or "Stream i : End RegSeqno" where i identifies a stream, from 0 through 15). Previously the stream sequence numbers were not correctly maintained if the instance had helper writer processes (spawned off by the Receiver Server when started with MUPIP REPLICATE -RECEIVER -HELPERS).
      • When it encounters interprocess communication (IPC) shared memory & semaphores for a database file for which it does not have read-write permissions and which is currently open by no processes with read-write access, a MUPIP RUNDOWN with no arguments issues a DBRDONLY error message, and leaves both semaphores and shared memory intact. Previously, in this case it removed the semaphores while leaving the shared memory intact, an out-of-design condition which could result in errors to other processes accessing that database file. The workaround to clean up the out-of-design state, was to open and close the database with a read-write process (the recommended technique), or run MUPIP RUNDOWN as root (not recommended, as GT.M processes should be run as root only as a last resort).
      • MUPIP RUNDOWN on a database file on which updates are frozen (e.g., using MUPIP FREEZE -ON) preserves the freeze. Previously if a frozen database file had a corresponding shared memory segment, MUPIP RUNDOWN would release the freeze.
      • MUPIP RUNDOWN with no arguments detaches from shared memory segments as it moves from one Journal Pool to another. Previously, if the gtm_custom_errors environment variable of an instance was set to a non-null value and MUPIP RUNDOWN encountered a Journal Pool shared memory segment corresponding to the receiving side of a replication connection, it would report a MURPOOLRNDWNFL error on that Journal Pool but not detach from the shared memory segment before moving on to the next journal pool. Encountering a large number of such Journal Pools could potentially cause MUPIP RUNDOWN to exhaust available address space on a 32-bit architecture, and hit an address space limit, if configured, on a 64-bit architecture.
      • MUPIP RUNDOWN works correctly on database files using the MM access method. Previously it incorrectly issued an "Invalid argument" message if it also issued a DBNAMEMISMATCH error on that MM database.
      • A MUPIP SET -JOURNAL command that requires standalone access to the database file (for example turning replication on or off) works correctly. In GT.M versions V6.2-000 to V6.2-002A, it could in rare cases terminate abnormally with a segmentation fault (SIG-11).
      • GT.M correctly maintains database shared memory in some rare cases when a database file has QDBRUNDOWN enabled and processes with read-only access open the database file BEFORE processes with read-write access. Previously, it was possible for an associated shared memory segment with updates not yet applied to the database file on disk to be inadvertently deleted.
      • GT.M logs the LASTWRITERBYPAS message in the system log (syslog) file only once per database file for the time that it stays open. Previously, in rare cases it was possible for this message to be issued more than once.
      • Helper processes (started with the GT.M replication Update Process) work correctly if they need to issue a LASTWRITERBYPAS message to the syslog. Previously they terminated abnormally with a segmentation fault (SIG-11).

      (GTM-8137) [!New Feature!]

    • MUPIP LOAD accepts a broader range of labels; label second lines containing "ZWR", "GLO", or the pattern produced by MUPIP EXTRACT and %GO automatically determine a format. Starting with V6.2-001, LOAD required the second line be either the exact format produced by MUPIP EXTRACT and ^%GO or under some conditions have a second line ending in "; ZWR" or "; GLO". In addition, MUPIP LOAD accepts files with DOS style termination. For -FORMAT={ZWR|GO} files not produced by MUPIP EXTRACT or %GO, the first line of the label must contain the case insensitive text "UTF-8" for UTF-8 mode files and the second line should contain the case insensitive test "ZWR" for zwr format or "GLO" for GO format and the two label lines must contain a total of more than 10 characters. (GTM-8223) [!New Feature!]

    • MUPIP replication compression supports the use of the IBM provided zlib library for AIX. Previously MUPIP replication compression required a custom compiled library. [AIX] (GTM-8225) [!New Feature!]

    • MUPIP REPLIC -BUFFSIZE=<bytes> has a maximum of 4294967288 (4GiB-8) for both -SOURCE and -RECEIVER; previously it had a maximum of 2147483647 (2GiB-1). (GTM-8326)

    • MUPIP TRIGGER -TRIGGERFILE presents a delete all confirmation prompt once, "Please enter Y or N:" (case insensitive). For any other response, MUPIP prompts again. Previously, every time MUPIP TRIGGER -TRIGGERFILE had to restart its transaction, it would repeat the prompt. Also, previously MUPIP TRIGGER -TRIGGERFILE would treat any response other than Y (case insensitive) as NO. (GTM-8342) [!New Feature!]

    • The distribution contains a source tarball for the reference encryption plugin, but no binaries. If you wish to use the reference encryption plugin, you must follow the instructions to compile it from the source in the tarball. Previously the distribution included binaries. Although not backwards compatible, we took this step because variations in encryption libraries meant that we could not provide a single binary that was guaranteed to run across Supported platforms with the robustness we require of GT.M. Note that when compiling the encryption plug-in, you should always review the makefile to ensure that all required dependencies in the makefile are installed on your system, and edit as needed to ensure that the locations of the header and library paths are correct for your system. (GTM-8361) [!New Feature!]

    • Repeated invocations of MUPIP JOURNAL ROLLBACK/RECOVER work correctly in case prior invocations terminated with certain errors. Previously, if at least two ROLLBACK or RECOVER commands terminated incompletely (say due to a GTM-E-MEMORY error) AND a MUPIP SET JOURNAL occurred between the interrupted commands, a subsequent ROLLBACK or RECOVER command could terminate abnormally with a GTMASSERT error even after correcting the cause of the original errors (say by raising the ulimit memory setting to avoid GTM-E-MEMORY errors). FIS recommends against unnecessarily changing journal files in the middle of operational processes such as ROLLBACK or RECOVER. (GTM-8394)

    • The Source Server correctly identifies the current journal file in the presence of a concurrent journal file switch. Previously, on rare occasion (made somewhat less rare by specifying the -JNLFILEONLY option to the Source Server) the Source Server would fail to identify the current journal file, issue a NOPREVLINK error, and exit. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8410)

    • See GTM-7658. (GTM-8420)

    • A Receiver Server started with -autorollback remains active even if an online rollback does not change the state of the database. Previously a Receiver Server started with -autorollback would shutdown if an automatic online rollback did not change the state of the database. (GTM-8421)

    • See GTM-6388. (GTM-8422)

    • The Receiver Server (MUPIP) correctly handles replication record conversion for large transactions from prior GT.M releases. A regression in GT.M V6.2-000 caused the Receiver Server to hang when the conversion size of records from a single transaction replicated from V5.4-002B or earlier exceeded 2MiB. (GTM-8423)

    • The Update Process receiving a replication stream works correctly in certain edge cases when a concurrent online rollback runs on the instance. Previously, the Update Process could terminate with a GTMASSERT error or hang and block further updates for potentially arbitrary periods of time. This was only encountered in the GT.M development environment, and was never reported by a user. (GTM-8425)

    • MUPIP INTEG appropriately reports large values; previously large amounts could overflow and cause erroneous reports. (GTM-8428)

    • Epoch tapering performs properly for a rare edge case. Previously, on very rare occasions, epoch tapering could encounter a divide-by-zero error. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8443)

    • The Source Server updates the resync sequence number in the replication instance file every 60 seconds. Internal testing pointed to a few timing windows where the resync sequence number was not updated for over 90 seconds. (GTM-8461)

    • MUPIP EXTRACT on an encrypted database instance creates valid binary extract files regardless of the region mapping. Previously, MUPIP EXTRACTs on instances with multiple regions pointing to the same database file could result in invalid extract files, that MUPIP LOAD could not process. The workaround was to use a global directory with regions merged so that each database file was referenced in just one segment. (GTM-8464)

    • When a Source Server starts replicating updates from a newer generation journal file, it closes any prior generation of that journal file that it has open. Previously, it closed open journal files only when switching to the Journal Pool, which was problematic for a Source Server started with the -jnlfileonly option. The workaround was to shut down and restart the Source Server. Additionally, the Source Server more efficiently handles the case where it has a large number of journal files open - a common situation when its receiving secondary instance starts with a significant backlog, forcing the Source Server to chain through large numbers of prior generation journal files. (GTM-8468)

    • See GTM-7831. (GTM-8470)

    • When completing a TLS renegotiation, the source server places a "Sending REPL_RENEG_COMPLETE" in its log file after a "REPL_RENEG_ACK received" message and before a "Sent REPL_RENEG_COMPLETE" message; previously it did not record this event. (GTM-8478)

    • MUPIP REORG limits its global buffer usage to the value specified by the gtm_poollimit environment variable, or, by default, if gtm_poollimit is not defined, to 64 buffers. Previously MUPIP REORG did not restrict its use of global buffers although the documentation stated that it did. We are aware of some issues with gtm_poollimit and recommend the following until the next release: avoid using it for processes that make extended global references or run MUPIP TRIGGER. (GTM-8479)

    • MUPIP BACKUP -DATABASE now attempts to preserve, and potentially restore, sparseness in database files. Previously, MUPIP BACKUP -DATABASE resulted in backup database files that were fully allocated. In the case of large but sparse database files, this could produce backup database files that used substantially more storage than the original database files. To remove sparseness from backup database files, use the fallocate command on Linux, or copy them to another location using the cp command on AIX. (GTM-8480) [!New Feature!]

    • MUPIP INTEG -FAST handles certain obscure integrity conditions correctly. Previously, these conditions could result in a REGSSFAIL error (AIX) or KILLBYSIGSINFO1 (signal 11) fatal error and core dump (Linux). MUPIP INTEG without the -FAST qualifier was not affected. (GTM-8481)

    • MUPIP JOURNAL correctly issues FILEPARSE errors for invalid paths; previously FILEPARSE errors would result in a SIG-11. (GTM-8485)

    • Shutting down all Source Server processes when GT.M processes are still accessing a database file does not generate inappropriate REPLINSTMATCH errors. (GTM-8487)

    • MUPIP BACKUP -ONLINE creates a usable backup of the replication instance file on a secondary instance. Previously, in rare cases, it could create a backup instance file that would cause the secondary to be out of sync with the currently replicating primary. Also, the replication instance file header on disk stores the current journal sequence number whenever a new history record gets added to the instance file. Previously this was not maintained which meant a MUPIP REPLIC -EDIT -SHOW command on the instance file potentially returned stale information on a live replicated environment. These issues were only observed in the GT.M development environment, and never reported by a user. (GTM-8494)

    • MUPIP commands that need standalone access, for example, MUPIP SET -REPLICATION=ON, issue a MUUSERLBK error on a crashed replication-enabled database, and MUUSERECOV error in case of a non-replicated-but-journaled database. Previously, the MUPIP commands would attempt a rundown regardless of the replication and journaling state of the database, potentially resulting in an unrecoverable database. Also MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -ROLLBACK -FORWARD now issue a MUUSERECOV or MUUSERLBK error in case the database shared memory segment exists. In this case, only a MUPIP JOURNAL -RECOVER -BACKWARD or MUPIP JOURNAL -ROLLBACK -BACKWARD can correctly flush the updates from shared memory to the database file on disk. Previously MUPIP JOURNAL -RECOVER -FORWARD used to proceed with the recovery potentially creating a corrupt database file. Also, MUPIP RUNDOWN issues a MUUSERLBK error on a crashed replication-enabled database even if the database has NOBEFORE_IMAGE journaling. Previously, it used to issue a MUUSERECOV error in this case. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8502) [!New Feature!]

    • Replication from an originating primary instance A to business continuity instance B and a supplementary instance P to an instance downstream Q (i.e., B<-A->P->Q) is more robust. Previously, if there was at least one switchover between A and B while the P->Q link was operating (i.e., from B<-A->P->Q to A<-B->P->Q) followed by a disruption in the P->Q replication connection, the automatic reconnect incorrectly concluded that P and Q were out of sync and the receiver server on Q incorrectly terminated. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8507)

    Other

    • The DSE ALL -CLEARCORRUPT qualifier sets the CORRUPT_FILE file header to FALSE for all GDS regions. Use the ALL -CLEARCORRUPT qualifier only after receiving instructions from your GT.M support channel. Previously, there was no single command to clear the CORRUPT_FILE to FALSE for all regions. (GTM-7199)

    • ^%RI correctly responds to a yes answer to the "Formfeed delimited <No>? " question, correctly places its output even if the output is sent to a directory without specifying a trailing slash (/), appropriately restores the characteristics of $PRINCIPAL that it adjusts, and accepts "DOS" line terminations (<CR><LF> instead of <LF>) at the end of input file lines. Previously it ignored a "YES" form-feed answer, prepended the directory name to the routines, changed the characteristics of the principal device and retained <CR>s at the end of input file lines, which resulted in compilation errors.(GTM-7658) [!New Feature!]

    • Created processes inherit only those open files that they should inherit. Previously unintended file sharing with non-GT.M executables could cause rare file handling errors. Non-GT.M executables can be run via ZSYSTEM, PIPE, MUPIP replication filters, and the gtm_procstuck_exec environment variable. (GTM-8009)

    • ^%GI accepts records up to the maximum string length (currently 1MiB). Previously it was limited to 8KiB for ZWR format and 2044 bytes for GO format. (GTM-8022) [!New Feature!]

    • The GT.M encryption plugin works correctly when $gtm_dist points to the utf8 subdirectory of the GT.M installation, as it should for UTF-8 mode processes. Previously, pointing $gtm_dist to the utf8 subdirectory resulted in the encryption plugin failing to load with a CRYPTDLNOOPEN2 error. The workaround was to replace the symbolic link plugin in the utf8 directory with a copy of the plugin directory from the main GT.M installation directory. This was originally fixed in V6.2-000, but was inadvertently omitted from the release notes. (GTM-8028)

    • In the event that a process detects a certain class of inconsistencies in the Journal Pool, it generates a core file (but does not terminate), and forces replication to continue from the journal files. This causes replication to reset to a known state. Replication resumes from the Journal Pool once a Source Server process determines that the updates it needs to replicate are in the Journal Pool. (GTM-8076)

    • V63-000A Peer replication is a type of bi-directional replication that uses GT.M triggers. Subsets of application logic which do not need update / transaction serialization, but which can benefit by aggregating updates from separate instances, can be deployed using peer replication. For example, financial transactions on a bank account must be serialized because each transaction depends on the result of the previous transaction on that account; balance inquiries need not be serialized because, while an inquiry to an account depends on the last financial transaction on that account, it does not depend on the last inquiry to that account. A reference implementation of GT.M peer replication is available as a plugin that you can add to your application (the reference implementation of a plugin is code that you can use as-is if it meets your needs, or adapt to your needs as appropriate; an existing example is the POSIX plugin). Plugins are not part of the GT.M core release but are separately released packages. The plugin includes a detailed readme file on implementing peer replication using the plugin. (GTM-8325)

    • A GT.M process waits for 500 ms before re-attempting to start gtmsecshr. As a consequence of a regression introduced in a previous version, while processing a timed event, GT.M waited only 3 milliseconds between attempts which could generate unnecessary syslog messages. (GTM-8395)

    • The %MPIECE utility NEWs all local variables except its arguments. Previously it could disrupt the state of a caller's local variables. (GTM-8403)

    • Journal record time stamps are more closely aligned with $HOROLOG and the timekeeping used for the HANG function. Previously there was some evidence that a global SET, HANG 1, global SET might occasionally yield two journal records in with the same time stamp. (GTM-8416)

    • The build dependencies in the source code for GT.M released under a free / open source software license support a greater variety of environments. GT.M V6.2-002/-002A builds failed in some build environments with the error: "fatal error: xfer_desc.i: No such file or directory". (GTM-8429)

    • The gtminstall script now honors the −−copyenv, −−copyexec and −−group-restriction options; previously these options caused the script to fail. (GTM-8441)

    • Enhance infohub_profile.sh to allow for one sitewide configuration file named custom_infohub_site.sh located in the installation directory. Previously, each user would need to configure infohub_site.sh in their $HOME directory. The InfoHub database instance gleaners operated through a PipeLine service now include information about each of the 16 Source Server slots. Previously this information was not available. (GTM-8449) [!New Feature!]

    • DSE manages output so it appears in the intended order. In versions, from GT.M V6.2-000 to GT.M V6.2-002A inclusive, when stdout and stderr for DSE invocation were assigned to the same file or terminal, DSE sometimes presented output in an incorrect order. There was no issue if stderr and stdout were directed to different destinations - output always went to stderr. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8458)

    • When starting gtmsecshr, GT.M clears environment variables that gtmsecshr does not need. Previously, it set them to the empty string (""), which could result in benign ARCTLMAXLOW warnings in the syslog. (GTM-8471)

    • DSE interprets the keys on damaged blocks appropriately; previously moving between a good block and a damaged block could cause DSE to report the wrong key interpretation. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8495)

    • DSE uses the original values used to create shared memory in case other values have been written to the file header. Previously mismatched values between shared memory and the file header prevented DSE from attaching to an active database. Note that such a scenario would require explicit abuse or misuse of DSE, and could not happen accidentally. Please remember that:

      • As a low level database repair tool of last resort, DSE assumes a knowledgeable user, and does no edit checking of input values. Do not use DSE to make routine changes, and do not use DSE to change a parameter if you can accomplish the same goal with MUPIP. As the normal system administration and operations tool, MUPIP has the ability to change parameters you might normally need to change, and it does check that input values are reasonable.
      • Changing fileheader parameters with DSE should normally be performed with stand-alone access. Change fileheader parameters on an open database only under the guidance of an expert GT.M support channel.

      This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8511)

    • The −−xec command line option of the %XCMD utility program is optional. Previously, it was required. (GTM-8514)

    • V63-000A At the direct mode prompt, GT.M ignores escape sequences longer than 16 bytes, however generated. Previously an escape sequence longer than 16 bytes could cause abnormal process termination. Note that such long escape sequences are not meaningful to GT.M, which ignores all escape sequences except those mapping to the limited set of terminfo capabilities documented in the "Using Terminals" section of Chapter 9 (Input/Output Processing) of the GT.M Programmers Guide. (GTM-8521)

    • V63-000A libgtmutil.so no longer includes extraneous MUMPS routines. Previously the GT.M distribution included MUMPS routines that are used in building GT.M and were not intended for distribution. (GTM-8524)

    • V63-000A M-Profiling treats negative change in cumulative user/system/elapsed time, incorrectly returned by the operating system, as zero time change. Previously, in such cases the trace could include extremely large time values. (GTM-8541)

    • V63-000A GT.M issues a KILLBYSIGUINFO message (to syslog as well as stderr) with valid process-id and userid information when a process that is hung on an instance freeze is killed using a process-terminating signal (e.g. kill -QUIT). Previously, in this scenario, it used to issue a KILLBYSIGUINFO message with a value of 0 for the process-id (of killing and killer process) and userid (of killing process). (GTM-8552)

    More Information

    Additional information for GTM-7291 - MUPIP JOURNAL -ROLLBACK qualifiers

    Except as detailed below, qualifiers previously supported for MUPIP JOURNAL -ROLLBACK -BACKWARD are supported with MUPIP JOURNAL -ROLLBACK -FORWARD.

    The -BEFORE time qualifier applies to MUPIP JOURNAL -ROLLBACK, both -FORWARD and -BACKWARD. As for MUPIP JOURNAL -RECOVER, the -BEFORE qualifier specifies the time at which ROLLBACK stops applying updates to the database in its forward processing phase (i.e., no journal records with update times after the -BEFORE time are applied to the database). If -BEFORE (time-based) and -FETCHRESYNC/-RESYNC (sequence-number-based) are specified in the same MUPIP JOURNAL -ROLLBACK command, the qualifier that corresponds to an earlier database state or point in time prevails i.e. if the update corresponding to the sequence number obtained through the -FETCHRESYNC command happened at a later time relative to the -BEFORE qualifier, -BEFORE prevails and vice versa.

    The -CHAIN qualifier applies to MUPIP JOURNAL -ROLLBACK -FORWARD just as it does to MUPIP JOURNAL -RECOVER -FORWARD.

    Unlike MUPIP JOURNAL -RECOVER -FORWARD, MUPIP JOURNAL -ROLLBACK -FORWARD, accepts only -CHECKTN, which is the default, but does not accept -NOCHECKTN.

    -FENCES=NONE and FENCES=ALWAYS are not permitted for MUPIP JOURNAL -ROLLBACK (with -BACKWARD or -FORWARD); ROLLBACK supports -FENCES=PROCESS (the default option). Previously MUPIP JOURNAL -ROLLBACK -BACKWARD allowed -FENCES=NONE or -FENCES=ALWAYS which could cause incomplete transactions to be played as if they were complete and result in a database file potentially out-of-sync with its journal files.

    The -SINCE time qualifier applies to MUPIP JOURNAL -ROLLBACK -BACKWARD. As in MUPIP JOURNAL -RECOVER, the -SINCE qualifier specifies how far back in time MUPIP JOURNAL -ROLLBACK -BACKWARD should at least process (from the end of the journal file), before starting the forward processing. The actual turn-around point for -RECOVER and -ROLLBACK in each database region is an epoch in the journal files before or at the -SINCE time, but not after it.

    -NOVERIFY is the default for MUPIP JOURNAL -RECOVER -FORWARD as well as MUPIP JOURNAL -ROLLBACK -FORWARD, with the exception of MUPIP JOURNAL -RECOVER -FORWARD -NOCHECKTN for which -VERIFY remains the default. Previously, -VERIFY was the default for MUPIP JOURNAL -RECOVER -FORWARD. -VERIFY remains the default for all other MUPIP JOURNAL commands (including MUPIP JOURNAL -RECOVER -BACKWARD and MUPIP JOURNAL -ROLLBACK -BACKWARD).

    The -FETCHRESYNC, -ONLINE, and -RSYNC_STRM qualifiers are not supported for MUPIP JOURNAL -ROLLBACK -FORWARD.

    Additional Information for GTM-8296 - %PEEKBYNAME()

    The format of the %PEEKBYNAME() function is %PEEKBYNAME(field[,regindex][,format]) where field specifies the type of information to be returned, in the format: control_block[.field].* Some control_blocks are:

    • gd_region - fields from the global directory typically accessed via GDE using a SHOW command; remember that these values are only used when MUPIP CREATE creates new database files.

    • gtmsource_local_struct - fields from the replication instance file, and typically accessed using MUPIP REPLICATE.

    • jnl_buffer - fields from journaling control structures typically accessed using DSE DUMP FILEHEADER

    • jnlpool_ctl_struct - journal Pool fields typically accessed using MUPIP REPLICATE.

    • node_local - fields from database shared memory that are not part of the fileheader, typically accessed using DSE DUMP FILEHEADER.

    • recvpool_ctl_struct - receive Pool fields (on an instance receiving a replication stream) typically accessed using MUPIP REPLICATE.

    • repl_inst_hdr.inst_info - replication fields that change infrequently, if ever.

    • sgmnt_data - fields from database shared memory also part of the database fileheader, typically accessed using DSE DUMP FILEHEADER.

    The optional second expression specifies a region name, structure index or a base address associated with the first (field name) argument. The choice is governed by the following rules applied in the following order:

    • If the value is a hexadecimal number in the form of 0xhhhhhhhh[hhhhhhhh], then PEEKBYNAME uses it as the base address of the data to fetch. Also in this case, the offset, length, and type are taken from the field specified in the first expression (field). For more information, see the description of the "PEEK" mnemonic in $ZPEEK(). FIS recommends that you not use a hexadecimal number except under the direction of your GT.M support channel.

    • If the first expression refers to one of the region-related structures supported by the $ZPEEK() function, PEEKBYNAME treats this second expression as a region name.

    • If the first expression refers to one of the replication related structures supported by the $ZPEEK() function that are indexed, PEEKBYNAME treats this second expression as an integer index value.

    • For those structures supported by the $ZPEEK() function that do not accept an argument, this second expression must be NULL or left unspecified.

    The optional third expression specifies the output format in one character as defined in the "format" argument in the $ZPEEK() documentation. This argument overrides the automatic format detection by the %PEEKBYNAME utility. FIS recommends that you not use the third argument except under the direction of your GT.M support channel.

    Examples:

    GTM>write $$^%PEEKBYNAME("gd_region.max_key_size","DEFAULT") ; Max key size for region DEFAULT
+

    The reason to block subsequent MUPIP REORG -ENCRYPT operations upon completion of one is to provide time for a backup of the entire database before enabling further key changes. MUPIP SET -ENCRYPTIONCOMPLETE reports an error for any database region for which MUPIP REORG -ENCRYPT has not completed.

    The above changes necessitated certain alterations of the encryption plugin API (for other API changes, see GTM-8336).

    (GTM-6310) [!New Feature!]

  • See GTM-8137. (GTM-6317)

  • MUPIP EXTRACT and MUPIP JOURNAL -EXTRACT are faster. While improvements you see will depend on the circumstances of your configuration and environment, in testing in the GT.M development environment, GO and ZWR formatted extracts completed in as much as three to four times faster than before. (GTM-6388)

  • On AIX, GT.M uses the AIX provided ICU libraries when gtm_icu_version is not defined. Previously GT.M required users to build the ICU libraries. [AIX] (GTM-6858) [!New Feature!]

  • With the -ZEROBACKLOG qualifier, a MUPIP REPLICATE -SOURCE -SHUTDOWN command shuts down the Source Server either when the backlog goes to zero, or the timeout expires, whichever occurs first. (GTM-6928) [!New Feature!]

  • MUPIP JOURNAL -ROLLBACK recognizes the -FORWARD qualifier to specify it apply update records in journal files to backed up copies of database files in order to bring them to the same state that MUPIP JOURNAL -ROLLBACK -BACKWARD "*" would bring crashed database files. Unlike MUPIP JOURNAL -ROLLBACK -BACKWARD, MUPIP JOURNAL -ROLLBACK -FORWARD accepts either a comma-delimited list of region names or "*", indicating the journal files associated with all regions in the current Global Directory. A MUPIP JOURNAL -ROLLBACK -FORWARD "*" command does what a MUPIP JOURNAL -RECOVER -FORWARD "*" would do except that the -ROLLBACK also updates sequence number related fields in the database file header, and ensures update serialization across regions - MUPIP JOURNAL -RECOVER can leave one database region ahead of another region and cannot ensure database Consistency across regions, whereas MUPIP JOURNAL -ROLLBACK can ensure Consistency. Databases recovered with MUPIP JOURNAL -ROLLBACK can therefore be used in replicated instances. Note that, in the context of -RECOVER and -ROLLBACK, the "*" indicates the use of all the appropriate journal files in all the replicated regions and the quotes prevent inappropriate expansion by the OS shell. MUPIP JOURNAL -ROLLBACK -FORWARD leaves the journaling state turned off in database files (as does MUPIP JOURNAL -RECOVER -FORWARD), which in turn means that replication is also turned off; journaling should be re-enabled, and replication turned on, before database files are used in environments where they can be updated, but can be left off if subsequent access is read-only. After a MUPIP JOURNAL -ROLLBACK -FORWARD, the replication instance file needs to be recreated as part of turning replication on in the recovered database. MUPIP JOURNAL -ROLLBACK -FORWARD can use both before-image and nobefore-image journal files. See the More Information section for details on qualifier use. In addition, MUPIP JOURNAL -ROLLBACK -BACKWARD output always includes the RLBKJNSEQ message; previously the output only included this if the rollback changed the database (i.e., the operation was not a no-op). Also, MUPIP JOURNAL -RECOVER -BACKWARD -BEFORE works even when -SINCE is not specified; previously such a command terminated with a JNLTMQUAL1 error. For more information, refer to Additional Information for GTM-7291 - MUPIP JOURNAL -ROLLBACK qualifiers. (GTM-7291) [!New Feature!]

  • GT.M accepts all ICU versions reported by "icu-config -version" for gtm_icu_version. Previously GT.M required the format of gtm_icu_version to be <ICU Major Version> "." <ICU Minor Version> with no trailing digits, and required ICU versions 49 & higher (i.e., with the new ICU numbering scheme) to be specified as 4.9, 5.0, etc. (GTM-7375) [!New Feature!]

  • An improvement in database replication communication between Source and Receiver Servers reduces delays. Previously, a busy Source Server, for example, one searching through journal files to find the transaction at which to resume communication with a replicating secondary instance with a large backlog, could ignore communications long enough for the Receiver Server to close the connection and begin a reconnection cycle, adding to the persistence of the backlog. Note that a Source Server started with -JNLFILEONLY always reads from the journal files. (GTM-5726) (GTM-7768)

  • MUPIP SET recognizes the -SPIN_SLEEP_LIMIT=n where n is decimal maximum number rounded up to the nearest power of two and turned into a hexadecimal mask that determines the maximum number of nanoseconds for processes to sleep while waiting to obtain critical sections for shared resources, principally those involving databases. The default is zero (0) which causes the process to return control to the UNIX kernel to be rescheduled with no explicit delay. When the value is non-zero, the process waits for a random value between zero (0) and the maximum value permitted by the mask. DSE CHANGE -FILEHEADER -SPIN_SLEEP_MASK provides a means to directly set the hexadecimal value of the mask, which appears in DSE DUMP -FILEHEADER output with the label "Spin sleep time mask." Previously, processes always rescheduled themselves with no delay. In addition, MUPIP SET (and DSE) accept a 0 value for -SLEEP_SPIN_COUNT, which eliminates the sleep loop in the mutual exclusion (mutex) facility so processes go straight from a hard spin to a queued wait. Previously, the -SLEEP_SPIN_COUNT qualifier was not recognized by MUPIP SET and processes that exhausted the hard spin count always did at least one (1) rescheduling operation. Except on the advice of your GT.M support channel, FIS recommends leaving the default values unchanged in production environments, until you have data from testing and benchmarking that demonstrates a benefit from a change. If none of its qualifiers are out of the range from minimum to maximum, MUPIP SET processes all qualifiers for each region applying them only if all are appropriate for the region and otherwise warning of any issues. Previously, MUPIP SET stopped at the first error and if some qualifiers required standalone access and others did not, applied only those requiring standalone access and silently ignored those that did not. If you have scripting that checks for correct completion of a MUPIP SET command, no changes are required to accommodate this change. However, if your scripting checks for and takes actions based on errors reported by MUPIP SET, you should test your script and revise it as needed. (GTM-7809) [!New Feature!]

  • MUPIP JOURNAL ROLLBACK fixes DBDANGER situations and therefore neither issues DBDANGER messages to syslog nor freezes an instance. Previously, MUPIP JOURNAL ROLLBACK could send DBDANGER messages to syslog even though it would fix the problem, and, when using the Instance Freeze facility with a DBDANGER in the custom errors file, a ROLLBACK issuing a DBDANGER message would freeze until manually unfrozen. (GTM-7831)

  • GT.M replication uses the operating system and network to perform flow control. Previously, the Source and Receiver Servers performed flow control, as a consequence of which the Receiver Server could flood the socket connection with flow control messages, leading to a large number of log messages and an occasional hang in replication processing. (GTM-7838)

  • MUPIP LOAD accepts negative values in ZWR format input such as that produced by %GO. Previously, such a value caused a LOADFILERR. The workaround was to use GO format or edit the file to add a pair of double-quotes around the negative value. (GTM-8020)

  • GT.M can be configured to permit more than 32,767 processes to concurrently access a database file. In a replicated environment, to permit one or more database files to be concurrently accessed by more than 32,767 updating processes also requires the replication instance file to be configured to permit concurrent access by more than 32,767 processes. The default behavior is to limit the number of processes accessing a database file or instance file to 32,767. This permission is effected by the QDBRUNDOWN flags in database file headers and in replication instance files. When an open database file or replication instance file with QDBRUNDOWN set is first concurrently accessed by more than 32,767 processes, GT.M (a) logs a NOMORESEMCNT message in the system log, and (b) stops counting the number of attached processes. This means that GT.M cannot recognize when the number of attached processes reaches zero (0) in order to release the corresponding shared resources, and therefore requires explicit manual clean up of resources for an orderly shutdown. Previously, exceeding 32Ki attachments to shared resources caused a DBFILERR, CRITSEMFAIL error with an ERANGE status for database and replication instance files, as it still does when QDBRUNDOWN is not set.

    Except in application configurations that require it, FIS recommends not setting QDBRUNDOWN. Not setting QDBRUNDOWN allows GT.M to clean up resources, instead of putting the burden on the operational procedures. Where GT.M cannot perform an orderly shutdown, an explicit, clean shutdown must be performed as follows:

    • Replicated instances require a MUPIP JOURNAL -ROLLBACK -BACKWARD "*" executed after the MUPIP REPLICATE SOURCE -SHUTDOWN command (remember that even instances receiving a replication stream have one or more Source Servers).
    • Database files that are journaled but not part of a replication instance require a MUPIP JOURNAL -RECOVER -BACKWARD command.
    • Database files that are not journaled (and hence not replicated) require a MUPIP RUNDOWN command.

    MUPIP REPLICATE -INSTANCE_CREATE -[NO]QDBRUNDOWN controls the QDBRUNDOWN setting of a replication instance file when it is created. For an existing replication instance file, requiring stand-alone access (i.e., the instance must not have an existing Journal Pool), MUPIP REPLICATE -EDITINSTANCE -[NO]QDBRUNDOWN controls the QDBRUNDOWN setting. Specifying -QDBRUNDOWN turns it ON, and -NOQDBRUNDOWN turns it OFF. MUPIP REPLICATE -EDITINSTANCE -SHOW displays the current QDBRUNDOWN setting of an instance file as "HDR Quick database rundown is active", reported as TRUE or FALSE. Note that QDBRUNDOWN is an existing setting in database files. See the release note for GTM-8296 on accessing the QDBRUNDOWN setting using %PEEKBYNAME().

    In support of this enhancement:

    • As all processes must use the same setting of QDBRUNDOWN, changing the QDBRUNDOWN setting requires standalone access; previously it did not for database files, and was not meaningful for replication instance files.
    • MUPIP RUNDOWN issues a DBRDONLY error if it encounters a database file with read-only permissions (no read-write permission) and the database shared memory indicates that the number of attached processes exceeded 32Ki at some point after it was opened. Databases that exceed the 32Ki counter need a process with read-write ability to perform the required rundown/recover/rollback.

    The work to develop this enhancement also addressed several issues. These issues were only observed in the GT.M development environment, and were never reported by a user.

    • Endian conversion works correctly in the rare case that the database is opened by a process after MUPIP ENDIANCVT starts converting the endianness of a database, and before it blocks other processes from opening the database. Previously, this could result in a database with structural damage requiring manual repair.
    • MUPIP JOURNAL -SHOW=HEADER on a journal file of a supplementary instance reports correct stream sequence numbers (displayed as "Stream i : Start RegSeqno" or "Stream i : End RegSeqno" where i identifies a stream, from 0 through 15). Previously the stream sequence numbers were not correctly maintained if the instance had helper writer processes (spawned off by the Receiver Server when started with MUPIP REPLICATE -RECEIVER -HELPERS).
    • When it encounters interprocess communication (IPC) shared memory & semaphores for a database file for which it does not have read-write permissions and which is currently open by no processes with read-write access, a MUPIP RUNDOWN with no arguments issues a DBRDONLY error message, and leaves both semaphores and shared memory intact. Previously, in this case it removed the semaphores while leaving the shared memory intact, an out-of-design condition which could result in errors to other processes accessing that database file. The workaround to clean up the out-of-design state, was to open and close the database with a read-write process (the recommended technique), or run MUPIP RUNDOWN as root (not recommended, as GT.M processes should be run as root only as a last resort).
    • MUPIP RUNDOWN on a database file on which updates are frozen (e.g., using MUPIP FREEZE -ON) preserves the freeze. Previously if a frozen database file had a corresponding shared memory segment, MUPIP RUNDOWN would release the freeze.
    • MUPIP RUNDOWN with no arguments detaches from shared memory segments as it moves from one Journal Pool to another. Previously, if the gtm_custom_errors environment variable of an instance was set to a non-null value and MUPIP RUNDOWN encountered a Journal Pool shared memory segment corresponding to the receiving side of a replication connection, it would report a MURPOOLRNDWNFL error on that Journal Pool but not detach from the shared memory segment before moving on to the next journal pool. Encountering a large number of such Journal Pools could potentially cause MUPIP RUNDOWN to exhaust available address space on a 32-bit architecture, and hit an address space limit, if configured, on a 64-bit architecture.
    • MUPIP RUNDOWN works correctly on database files using the MM access method. Previously it incorrectly issued an "Invalid argument" message if it also issued a DBNAMEMISMATCH error on that MM database.
    • A MUPIP SET -JOURNAL command that requires standalone access to the database file (for example turning replication on or off) works correctly. In GT.M versions V6.2-000 to V6.2-002A, it could in rare cases terminate abnormally with a segmentation fault (SIG-11).
    • GT.M correctly maintains database shared memory in some rare cases when a database file has QDBRUNDOWN enabled and processes with read-only access open the database file BEFORE processes with read-write access. Previously, it was possible for an associated shared memory segment with updates not yet applied to the database file on disk to be inadvertently deleted.
    • GT.M logs the LASTWRITERBYPAS message in the system log (syslog) file only once per database file for the time that it stays open. Previously, in rare cases it was possible for this message to be issued more than once.
    • Helper processes (started with the GT.M replication Update Process) work correctly if they need to issue a LASTWRITERBYPAS message to the syslog. Previously they terminated abnormally with a segmentation fault (SIG-11).

    (GTM-8137) [!New Feature!]

  • MUPIP LOAD accepts a broader range of labels; label second lines containing "ZWR", "GLO", or the pattern produced by MUPIP EXTRACT and %GO automatically determine a format. Starting with V6.2-001, LOAD required the second line be either the exact format produced by MUPIP EXTRACT and ^%GO or under some conditions have a second line ending in "; ZWR" or "; GLO". In addition, MUPIP LOAD accepts files with DOS style termination. For -FORMAT={ZWR|GO} files not produced by MUPIP EXTRACT or %GO, the first line of the label must contain the case insensitive text "UTF-8" for UTF-8 mode files and the second line should contain the case insensitive test "ZWR" for zwr format or "GLO" for GO format and the two label lines must contain a total of more than 10 characters. (GTM-8223) [!New Feature!]

  • MUPIP replication compression supports the use of the IBM provided zlib library for AIX. Previously MUPIP replication compression required a custom compiled library. [AIX] (GTM-8225) [!New Feature!]

  • MUPIP REPLIC -BUFFSIZE=<bytes> has a maximum of 4294967288 (4GiB-8) for both -SOURCE and -RECEIVER; previously it had a maximum of 2147483647 (2GiB-1). (GTM-8326)

  • MUPIP TRIGGER -TRIGGERFILE presents a delete all confirmation prompt once, "Please enter Y or N:" (case insensitive). For any other response, MUPIP prompts again. Previously, every time MUPIP TRIGGER -TRIGGERFILE had to restart its transaction, it would repeat the prompt. Also, previously MUPIP TRIGGER -TRIGGERFILE would treat any response other than Y (case insensitive) as NO. (GTM-8342) [!New Feature!]

  • The distribution contains a source tarball for the reference encryption plugin, but no binaries. If you wish to use the reference encryption plugin, you must follow the instructions to compile it from the source in the tarball. Previously the distribution included binaries. Although not backwards compatible, we took this step because variations in encryption libraries meant that we could not provide a single binary that was guaranteed to run across Supported platforms with the robustness we require of GT.M. Note that when compiling the encryption plug-in, you should always review the makefile to ensure that all required dependencies in the makefile are installed on your system, and edit as needed to ensure that the locations of the header and library paths are correct for your system. (GTM-8361) [!New Feature!]

  • Repeated invocations of MUPIP JOURNAL ROLLBACK/RECOVER work correctly in case prior invocations terminated with certain errors. Previously, if at least two ROLLBACK or RECOVER commands terminated incompletely (say due to a GTM-E-MEMORY error) AND a MUPIP SET JOURNAL occurred between the interrupted commands, a subsequent ROLLBACK or RECOVER command could terminate abnormally with a GTMASSERT error even after correcting the cause of the original errors (say by raising the ulimit memory setting to avoid GTM-E-MEMORY errors). FIS recommends against unnecessarily changing journal files in the middle of operational processes such as ROLLBACK or RECOVER. (GTM-8394)

  • The Source Server correctly identifies the current journal file in the presence of a concurrent journal file switch. Previously, on rare occasion (made somewhat less rare by specifying the -JNLFILEONLY option to the Source Server) the Source Server would fail to identify the current journal file, issue a NOPREVLINK error, and exit. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8410)

  • See GTM-7658. (GTM-8420)

  • A Receiver Server started with -autorollback remains active even if an online rollback does not change the state of the database. Previously a Receiver Server started with -autorollback would shutdown if an automatic online rollback did not change the state of the database. (GTM-8421)

  • See GTM-6388. (GTM-8422)

  • The Receiver Server (MUPIP) correctly handles replication record conversion for large transactions from prior GT.M releases. A regression in GT.M V6.2-000 caused the Receiver Server to hang when the conversion size of records from a single transaction replicated from V5.4-002B or earlier exceeded 2MiB. (GTM-8423)

  • The Update Process receiving a replication stream works correctly in certain edge cases when a concurrent online rollback runs on the instance. Previously, the Update Process could terminate with a GTMASSERT error or hang and block further updates for potentially arbitrary periods of time. This was only encountered in the GT.M development environment, and was never reported by a user. (GTM-8425)

  • MUPIP INTEG appropriately reports large values; previously large amounts could overflow and cause erroneous reports. (GTM-8428)

  • Epoch tapering performs properly for a rare edge case. Previously, on very rare occasions, epoch tapering could encounter a divide-by-zero error. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8443)

  • The Source Server updates the resync sequence number in the replication instance file every 60 seconds. Internal testing pointed to a few timing windows where the resync sequence number was not updated for over 90 seconds. (GTM-8461)

  • MUPIP EXTRACT on an encrypted database instance creates valid binary extract files regardless of the region mapping. Previously, MUPIP EXTRACTs on instances with multiple regions pointing to the same database file could result in invalid extract files, that MUPIP LOAD could not process. The workaround was to use a global directory with regions merged so that each database file was referenced in just one segment. (GTM-8464)

  • When a Source Server starts replicating updates from a newer generation journal file, it closes any prior generation of that journal file that it has open. Previously, it closed open journal files only when switching to the Journal Pool, which was problematic for a Source Server started with the -jnlfileonly option. The workaround was to shut down and restart the Source Server. Additionally, the Source Server more efficiently handles the case where it has a large number of journal files open - a common situation when its receiving secondary instance starts with a significant backlog, forcing the Source Server to chain through large numbers of prior generation journal files. (GTM-8468)

  • See GTM-7831. (GTM-8470)

  • When completing a TLS renegotiation, the source server places a "Sending REPL_RENEG_COMPLETE" in its log file after a "REPL_RENEG_ACK received" message and before a "Sent REPL_RENEG_COMPLETE" message; previously it did not record this event. (GTM-8478)

  • MUPIP REORG limits its global buffer usage to the value specified by the gtm_poollimit environment variable, or, by default, if gtm_poollimit is not defined, to 64 buffers. Previously MUPIP REORG did not restrict its use of global buffers although the documentation stated that it did. We are aware of some issues with gtm_poollimit and recommend the following until the next release: avoid using it for processes that make extended global references or run MUPIP TRIGGER. (GTM-8479)

  • MUPIP BACKUP -DATABASE now attempts to preserve, and potentially restore, sparseness in database files. Previously, MUPIP BACKUP -DATABASE resulted in backup database files that were fully allocated. In the case of large but sparse database files, this could produce backup database files that used substantially more storage than the original database files. To remove sparseness from backup database files, use the fallocate command on Linux, or copy them to another location using the cp command on AIX. (GTM-8480) [!New Feature!]

  • MUPIP INTEG -FAST handles certain obscure integrity conditions correctly. Previously, these conditions could result in a REGSSFAIL error (AIX) or KILLBYSIGSINFO1 (signal 11) fatal error and core dump (Linux). MUPIP INTEG without the -FAST qualifier was not affected. (GTM-8481)

  • MUPIP JOURNAL correctly issues FILEPARSE errors for invalid paths; previously FILEPARSE errors would result in a SIG-11. (GTM-8485)

  • Shutting down all Source Server processes when GT.M processes are still accessing a database file does not generate inappropriate REPLINSTMATCH errors. (GTM-8487)

  • MUPIP BACKUP -ONLINE creates a usable backup of the replication instance file on a secondary instance. Previously, in rare cases, it could create a backup instance file that would cause the secondary to be out of sync with the currently replicating primary. Also, the replication instance file header on disk stores the current journal sequence number whenever a new history record gets added to the instance file. Previously this was not maintained which meant a MUPIP REPLIC -EDIT -SHOW command on the instance file potentially returned stale information on a live replicated environment. These issues were only observed in the GT.M development environment, and never reported by a user. (GTM-8494)

  • MUPIP commands that need standalone access, for example, MUPIP SET -REPLICATION=ON, issue a MUUSERLBK error on a crashed replication-enabled database, and MUUSERECOV error in case of a non-replicated-but-journaled database. Previously, the MUPIP commands would attempt a rundown regardless of the replication and journaling state of the database, potentially resulting in an unrecoverable database. Also MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -ROLLBACK -FORWARD now issue a MUUSERECOV or MUUSERLBK error in case the database shared memory segment exists. In this case, only a MUPIP JOURNAL -RECOVER -BACKWARD or MUPIP JOURNAL -ROLLBACK -BACKWARD can correctly flush the updates from shared memory to the database file on disk. Previously MUPIP JOURNAL -RECOVER -FORWARD used to proceed with the recovery potentially creating a corrupt database file. Also, MUPIP RUNDOWN issues a MUUSERLBK error on a crashed replication-enabled database even if the database has NOBEFORE_IMAGE journaling. Previously, it used to issue a MUUSERECOV error in this case. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8502) [!New Feature!]

  • Replication from an originating primary instance A to business continuity instance B and a supplementary instance P to an instance downstream Q (i.e., B<-A->P->Q) is more robust. Previously, if there was at least one switchover between A and B while the P->Q link was operating (i.e., from B<-A->P->Q to A<-B->P->Q) followed by a disruption in the P->Q replication connection, the automatic reconnect incorrectly concluded that P and Q were out of sync and the receiver server on Q incorrectly terminated. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8507)

    • Other

    • The DSE ALL -CLEARCORRUPT qualifier sets the CORRUPT_FILE file header to FALSE for all GDS regions. Use the ALL -CLEARCORRUPT qualifier only after receiving instructions from your GT.M support channel. Previously, there was no single command to clear the CORRUPT_FILE to FALSE for all regions. (GTM-7199)

    • ^%RI correctly responds to a yes answer to the "Formfeed delimited <No>? " question, correctly places its output even if the output is sent to a directory without specifying a trailing slash (/), appropriately restores the characteristics of $PRINCIPAL that it adjusts, and accepts "DOS" line terminations (<CR><LF> instead of <LF>) at the end of input file lines. Previously it ignored a "YES" form-feed answer, prepended the directory name to the routines, changed the characteristics of the principal device and retained <CR>s at the end of input file lines, which resulted in compilation errors.(GTM-7658) [!New Feature!]

    • Created processes inherit only those open files that they should inherit. Previously unintended file sharing with non-GT.M executables could cause rare file handling errors. Non-GT.M executables can be run via ZSYSTEM, PIPE, MUPIP replication filters, and the gtm_procstuck_exec environment variable. (GTM-8009)

    • ^%GI accepts records up to the maximum string length (currently 1MiB). Previously it was limited to 8KiB for ZWR format and 2044 bytes for GO format. (GTM-8022) [!New Feature!]

    • The GT.M encryption plugin works correctly when $gtm_dist points to the utf8 subdirectory of the GT.M installation, as it should for UTF-8 mode processes. Previously, pointing $gtm_dist to the utf8 subdirectory resulted in the encryption plugin failing to load with a CRYPTDLNOOPEN2 error. The workaround was to replace the symbolic link plugin in the utf8 directory with a copy of the plugin directory from the main GT.M installation directory. This was originally fixed in V6.2-000, but was inadvertently omitted from the release notes. (GTM-8028)

    • In the event that a process detects a certain class of inconsistencies in the Journal Pool, it generates a core file (but does not terminate), and forces replication to continue from the journal files. This causes replication to reset to a known state. Replication resumes from the Journal Pool once a Source Server process determines that the updates it needs to replicate are in the Journal Pool. (GTM-8076)

    • V63-000A Peer replication is a type of bi-directional replication that uses GT.M triggers. Subsets of application logic which do not need update / transaction serialization, but which can benefit by aggregating updates from separate instances, can be deployed using peer replication. For example, financial transactions on a bank account must be serialized because each transaction depends on the result of the previous transaction on that account; balance inquiries need not be serialized because, while an inquiry to an account depends on the last financial transaction on that account, it does not depend on the last inquiry to that account. A reference implementation of GT.M peer replication is available as a plugin that you can add to your application (the reference implementation of a plugin is code that you can use as-is if it meets your needs, or adapt to your needs as appropriate; an existing example is the POSIX plugin). Plugins are not part of the GT.M core release but are separately released packages. The plugin includes a detailed readme file on implementing peer replication using the plugin. (GTM-8325)

    • A GT.M process waits for 500 ms before re-attempting to start gtmsecshr. As a consequence of a regression introduced in a previous version, while processing a timed event, GT.M waited only 3 milliseconds between attempts which could generate unnecessary syslog messages. (GTM-8395)

    • The %MPIECE utility NEWs all local variables except its arguments. Previously it could disrupt the state of a caller's local variables. (GTM-8403)

    • Journal record time stamps are more closely aligned with $HOROLOG and the timekeeping used for the HANG function. Previously there was some evidence that a global SET, HANG 1, global SET might occasionally yield two journal records in with the same time stamp. (GTM-8416)

    • The build dependencies in the source code for GT.M released under a free / open source software license support a greater variety of environments. GT.M V6.2-002/-002A builds failed in some build environments with the error: "fatal error: xfer_desc.i: No such file or directory". (GTM-8429)

    • The gtminstall script now honors the −−copyenv, −−copyexec and −−group-restriction options; previously these options caused the script to fail. (GTM-8441)

    • Enhance infohub_profile.sh to allow for one sitewide configuration file named custom_infohub_site.sh located in the installation directory. Previously, each user would need to configure infohub_site.sh in their $HOME directory. The InfoHub database instance gleaners operated through a PipeLine service now include information about each of the 16 Source Server slots. Previously this information was not available. (GTM-8449) [!New Feature!]

    • DSE manages output so it appears in the intended order. In versions, from GT.M V6.2-000 to GT.M V6.2-002A inclusive, when stdout and stderr for DSE invocation were assigned to the same file or terminal, DSE sometimes presented output in an incorrect order. There was no issue if stderr and stdout were directed to different destinations - output always went to stderr. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8458)

    • When starting gtmsecshr, GT.M clears environment variables that gtmsecshr does not need. Previously, it set them to the empty string (""), which could result in benign ARCTLMAXLOW warnings in the syslog. (GTM-8471)

    • DSE interprets the keys on damaged blocks appropriately; previously moving between a good block and a damaged block could cause DSE to report the wrong key interpretation. This issue was discovered in the GT.M development environment and was never reported by any user. (GTM-8495)

    • DSE uses the original values used to create shared memory in case other values have been written to the file header. Previously mismatched values between shared memory and the file header prevented DSE from attaching to an active database. Note that such a scenario would require explicit abuse or misuse of DSE, and could not happen accidentally. Please remember that:

      • As a low level database repair tool of last resort, DSE assumes a knowledgeable user, and does no edit checking of input values. Do not use DSE to make routine changes, and do not use DSE to change a parameter if you can accomplish the same goal with MUPIP. As the normal system administration and operations tool, MUPIP has the ability to change parameters you might normally need to change, and it does check that input values are reasonable.
      • Changing fileheader parameters with DSE should normally be performed with stand-alone access. Change fileheader parameters on an open database only under the guidance of an expert GT.M support channel.

      This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8511)

    • The −−xec command line option of the %XCMD utility program is optional. Previously, it was required. (GTM-8514)

    • V63-000A At the direct mode prompt, GT.M ignores escape sequences longer than 16 bytes, however generated. Previously an escape sequence longer than 16 bytes could cause abnormal process termination. Note that such long escape sequences are not meaningful to GT.M, which ignores all escape sequences except those mapping to the limited set of terminfo capabilities documented in the "Using Terminals" section of Chapter 9 (Input/Output Processing) of the GT.M Programmers Guide. (GTM-8521)

    • V63-000A libgtmutil.so no longer includes extraneous MUMPS routines. Previously the GT.M distribution included MUMPS routines that are used in building GT.M and were not intended for distribution. (GTM-8524)

    • V63-000A M-Profiling treats negative change in cumulative user/system/elapsed time, incorrectly returned by the operating system, as zero time change. Previously, in such cases the trace could include extremely large time values. (GTM-8541)

    • V63-000A GT.M issues a KILLBYSIGUINFO message (to syslog as well as stderr) with valid process-id and userid information when a process that is hung on an instance freeze is killed using a process-terminating signal (e.g. kill -QUIT). Previously, in this scenario, it used to issue a KILLBYSIGUINFO message with a value of 0 for the process-id (of killing and killer process) and userid (of killing process). (GTM-8552)

    More Information

    Additional information for GTM-7291 - MUPIP JOURNAL -ROLLBACK qualifiers

    Except as detailed below, qualifiers previously supported for MUPIP JOURNAL -ROLLBACK -BACKWARD are supported with MUPIP JOURNAL -ROLLBACK -FORWARD.

    The -BEFORE time qualifier applies to MUPIP JOURNAL -ROLLBACK, both -FORWARD and -BACKWARD. As for MUPIP JOURNAL -RECOVER, the -BEFORE qualifier specifies the time at which ROLLBACK stops applying updates to the database in its forward processing phase (i.e., no journal records with update times after the -BEFORE time are applied to the database). If -BEFORE (time-based) and -FETCHRESYNC/-RESYNC (sequence-number-based) are specified in the same MUPIP JOURNAL -ROLLBACK command, the qualifier that corresponds to an earlier database state or point in time prevails i.e. if the update corresponding to the sequence number obtained through the -FETCHRESYNC command happened at a later time relative to the -BEFORE qualifier, -BEFORE prevails and vice versa.

    The -CHAIN qualifier applies to MUPIP JOURNAL -ROLLBACK -FORWARD just as it does to MUPIP JOURNAL -RECOVER -FORWARD.

    Unlike MUPIP JOURNAL -RECOVER -FORWARD, MUPIP JOURNAL -ROLLBACK -FORWARD, accepts only -CHECKTN, which is the default, but does not accept -NOCHECKTN.

    -FENCES=NONE and FENCES=ALWAYS are not permitted for MUPIP JOURNAL -ROLLBACK (with -BACKWARD or -FORWARD); ROLLBACK supports -FENCES=PROCESS (the default option). Previously MUPIP JOURNAL -ROLLBACK -BACKWARD allowed -FENCES=NONE or -FENCES=ALWAYS which could cause incomplete transactions to be played as if they were complete and result in a database file potentially out-of-sync with its journal files.

    The -SINCE time qualifier applies to MUPIP JOURNAL -ROLLBACK -BACKWARD. As in MUPIP JOURNAL -RECOVER, the -SINCE qualifier specifies how far back in time MUPIP JOURNAL -ROLLBACK -BACKWARD should at least process (from the end of the journal file), before starting the forward processing. The actual turn-around point for -RECOVER and -ROLLBACK in each database region is an epoch in the journal files before or at the -SINCE time, but not after it.

    -NOVERIFY is the default for MUPIP JOURNAL -RECOVER -FORWARD as well as MUPIP JOURNAL -ROLLBACK -FORWARD, with the exception of MUPIP JOURNAL -RECOVER -FORWARD -NOCHECKTN for which -VERIFY remains the default. Previously, -VERIFY was the default for MUPIP JOURNAL -RECOVER -FORWARD. -VERIFY remains the default for all other MUPIP JOURNAL commands (including MUPIP JOURNAL -RECOVER -BACKWARD and MUPIP JOURNAL -ROLLBACK -BACKWARD).

    The -FETCHRESYNC, -ONLINE, and -RSYNC_STRM qualifiers are not supported for MUPIP JOURNAL -ROLLBACK -FORWARD.

    Additional Information for GTM-8296 - %PEEKBYNAME()

    The format of the %PEEKBYNAME() function is %PEEKBYNAME(field[,regindex][,format]) where field specifies the type of information to be returned, in the format: control_block[.field].* Some control_blocks are:

    • gd_region - fields from the global directory typically accessed via GDE using a SHOW command; remember that these values are only used when MUPIP CREATE creates new database files.

    • gtmsource_local_struct - fields from the replication instance file, and typically accessed using MUPIP REPLICATE.

    • jnl_buffer - fields from journaling control structures typically accessed using DSE DUMP FILEHEADER

    • jnlpool_ctl_struct - journal Pool fields typically accessed using MUPIP REPLICATE.

    • node_local - fields from database shared memory that are not part of the fileheader, typically accessed using DSE DUMP FILEHEADER.

    • recvpool_ctl_struct - receive Pool fields (on an instance receiving a replication stream) typically accessed using MUPIP REPLICATE.

    • repl_inst_hdr.inst_info - replication fields that change infrequently, if ever.

    • sgmnt_data - fields from database shared memory also part of the database fileheader, typically accessed using DSE DUMP FILEHEADER.

    The optional second expression specifies a region name, structure index or a base address associated with the first (field name) argument. The choice is governed by the following rules applied in the following order:

    • If the value is a hexadecimal number in the form of 0xhhhhhhhh[hhhhhhhh], then PEEKBYNAME uses it as the base address of the data to fetch. Also in this case, the offset, length, and type are taken from the field specified in the first expression (field). For more information, see the description of the "PEEK" mnemonic in $ZPEEK(). FIS recommends that you not use a hexadecimal number except under the direction of your GT.M support channel.

    • If the first expression refers to one of the region-related structures supported by the $ZPEEK() function, PEEKBYNAME treats this second expression as a region name.

    • If the first expression refers to one of the replication related structures supported by the $ZPEEK() function that are indexed, PEEKBYNAME treats this second expression as an integer index value.

    • For those structures supported by the $ZPEEK() function that do not accept an argument, this second expression must be NULL or left unspecified.

    The optional third expression specifies the output format in one character as defined in the "format" argument in the $ZPEEK() documentation. This argument overrides the automatic format detection by the %PEEKBYNAME utility. FIS recommends that you not use the third argument except under the direction of your GT.M support channel.

    Examples:

    GTM>write $$^%PEEKBYNAME("gd_region.max_key_size","DEFAULT") ; Max key size for region DEFAULT
 255
 GTM>

    LISTALL^%PEEKBYNAME

    Prints all the field mnemonics acceptable as the first argument to %PEEKBYNAME() on the current output device.

    LIST^%PEEKBYNAME(.output)

    Populates output variable with the type and size information indexed by the field mnemonics for all fields accepted by %PEEKBYNAME(). FIS recommends that you not use the results of this entryref except under the direction of your GT.M support channel.

    Labels for Selected Fields

    Below are selected fields for which you may find %PEEKBYNAME to be a useful alternative to running a DSE or MUPIP command in a PIPE device, and parsing the output. If there is a field that you wish to access using %PEEKBYNAME, please send questions to your GT.M support channel. We will get you an answer, and if it seems to us to be of general interest, we will add it to the %PEEKBYNAME user documentation.

    Region Parameters

    Calls to %PEEKBYNAME with the listed string as value of the first parameter, and the region name as the value of the second parameter, return the value. For example:

    GTM>write $$^%PEEKBYNAME("sgmnt_data.n_bts","DEFAULT") ; How many global buffers there are
 1000
diff --git a/articles/GTM_V6.3-001_Release_Notes.html b/articles/GTM_V6.3-001_Release_Notes.html
index ce5ffbc..9e9f6a2 100644
--- a/articles/GTM_V6.3-001_Release_Notes.html
+++ b/articles/GTM_V6.3-001_Release_Notes.html
@@ -275,7 +275,7 @@ If these will cause you hardship, please contact your FIS account manager or you
  to download the CONVDBKEYS.m program and follow instructions in the comments near the top of the program file. You can also download CONVDBKEYS.m from http://tinco.pair.com/bhaskar/gtm/doc/articles/downloadables/CONVDBKEYS.m. If you are using $gtm_dbkeys for database encryption, please convert master key files to libconfig format immediately after upgrading to V6.2-000. Also, modify your environment scripts to include the use of gtmcrypt_config environment variable.
    Compiling the Reference Implementation Plugin

    If you plan to use database encryption and TLS replication, you must compile the reference implementation plugin to match the shared library dependencies unique to your platform. The instructions for compiling the Reference Implementation plugin are as follows:

    1. Install the development headers and libraries for libgcrypt, libgpgme, libconfig, and libssl. On Linux, the package names of development libraries usually have a suffix such as -dev or -devel and are available through the package manager. For example, on Ubuntu_x86_64 a command like the following installs the required development libraries:

      sudo apt-get install libgcrypt11-dev libgpgme11-dev libconfig-dev libssl-dev

      Note that the package names may vary by distribution / version.

    2. Unpack $gtm_dist/plugin/gtmcrypt/source.tar to a temporary directory. 

      mkdir /tmp/plugin-build
 cd /tmp/plugin-build
 cp $gtm_dist/plugin/gtmcrypt/source.tar . 
-tar -xvf source.tar

    3. Follow the instructions in the README.

      • Open Makefile with your editor; review and edit the common header (IFLAGS) and library paths (LIBFLAGS) in the Makefile to reflect those on your system.

      • Define the gtm_dist environment variable to point to the absolute path for the directory where you have GT.M installed

      • Copy and paste the commands from the README to compile and install the encryption plugin with the permissions defined at install time

    Upgrading to GT.M V6.3-001A

    The GT.M database consists of four types of components- database files, journal files, global directories, and replication instance files. The format of some database components differs for 32-bit and 64-bit GT.M releases for the x86 GNU/Linux platform.

    GT.M upgrade procedure for V6.3-001A consists of 5 stages:

    Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V6.3-001A depends on your GT.M upgrade history and your current version.

    Stage 1: Global Directory Upgrade

    FIS strongly recommends you back up your Global Directory file before upgrading. There is no one-step method for downgrading a Global Directory file to an older format.

    To upgrade from any previous version of GT.M:

    • Open your Global Directory with the GDE utility program of GT.M V6.3-001A.

    • Execute the EXIT command. This command automatically upgrades the Global Directory.

    To switch between 32- and 64-bit global directories on the x86 GNU/Linux platform:

    1. Open your Global Directory with the GDE utility program on the 32-bit platform.

    2. On GT.M versions that support SHOW -COMMAND, execute SHOW -COMMAND -FILE=file-name. This command stores the current Global Directory settings in the specified file. .

    3. On GT.M versions that do not support GDE SHOW -COMMAND, execute the SHOW -ALL command. Use the information from the output to create an appropriate command file or use it as a guide to manually enter commands in GDE.

    4. Open GDE on the 64-bit platform. If you have a command file from 2. or 3., execute @file-name and then run the EXIT command. These commands automatically create the Global Directory. Otherwise use the GDE output from the old Global Directory and apply the settings in the new environment.

    An analogous procedure applies in the reverse direction.

    If you inadvertently open a Global Directory of an old 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 to downgrade to an old GT.M release:

    • Open the global directory with the GDE utility program of V6.3-001A.

    • Execute the SHOW -COMMAND -FILE=file-name command. This command stores the current Global Directory settings in the file-name command file. If the old version is significantly out of date, edit the command file to remove the commands that do not apply to the old format. Alternatively, you can use the output from SHOW -ALL or SHOW -COMMAND as a guide to manually enter equivalent GDE commands for the old version.

    Stage 2: Database Files Upgrade

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

    A V6 database file is a superset of a V5 database file and has potentially longer keys and records. Therefore, upgrading a database file requires no explicit procedure. After upgrading the Global Directory, opening a V5 database with a V6 process automatically upgrades fields in the database fileheader.

    A database created with V6 supports up to 992Mi blocks and is not backward compatible. V6 databases that take advantage of V6 limits on key size and records size cannot be downgraded. Use MUPIP DOWNGRADE -VERSION=V5 to downgrade a V6 database back to V5 format provided it meets the database downgrade requirements. For more information on downgrading a database, refer to Downgrading to V5 or V4.

    [Important] Important

    A V5 database that has been automatically upgraded to V6 can perform all GT.M V6.3-001A operations. However, that database can only grow to the maximum size of the version in which it was originally created. A database created on V5.0-000 through V5.3-003 has maximum size of 128Mi blocks. A database created on V5.4-000 through V5.5-000 has a maximum size of 224Mi blocks. A database file created with V6.0-000 (or above) can grow up to a maximum of 992Mi blocks. This means that, for example, the maximum size of a V6 database file having 8KiB block size is 7936GiB (8KiB*992Mi).

    [Important] Important

    In order to perform a database downgrade you must perform a MUPIP INTEG -NOONLINE. If the duration of the MUPIP INTEG exceeds the time allotted for an upgrade you should rely on a rolling upgrade scheme using replication.

    If your database has any previously used but free blocks from an earlier upgrade cycle (V4 to V5), you may need to execute the MUPIP REORG -UPGRADE command. If you have already executed the MUPIP REORG -UPGRADE command in a version prior to V5.3-003 and if subsequent versions cannot determine whether MUPIP REORG -UPGRADE performed all required actions, it sends warnings to the syslog requesting another run of MUPIP REORG -UPGRADE. In that case, perform any one of the following steps:

    • Execute the MUPIP REORG -UPGRADE command again, or

    • Execute the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command to stop the warnings.

    [Caution] Caution

    Do not run the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command unless you are absolutely sure of having previously run a MUPIP REORG -UPGRADE from V5.3-003 or later. An inappropriate DSE CHANGE -FILEHEADE -FULLY_UPGRADED=1 may lead to database integrity issues.

    You do not need to run MUPIP REORG -UPGRADE on:

    • A database that was created by a V5 MUPIP CREATE

    • A database that has been completely processed by a MUPIP REORG -UPGRADE from V5.3-003 or later.

    For additional upgrade considerations, refer to Database Compatibility Notes.

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

    You need to upgrade your database files only when there is a block format upgrade from V4 to V5. However, some versions, for example, database files 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.

    • 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.

    • Run the MUPIP REORG -UPGRADE command. This command upgrades all V4 blocks to V5 format.

    [Note] Note

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

    Database Compatibility Notes

    • Changes to the database file header may occur in any release. GT.M automatically upgrades database file headers as needed. Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.

    • Databases created with V5.3-004 through V5.5-000 can grow to a maximum size of 224Mi (234,881,024) blocks. This means, for example, that with an 8KiB block size, the maximum database file size is 1,792GiB; this is effectively the size of a single global variable that has a region to itself and does not itself span regions; a database consists of any number of global variables. A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128Mi to 224Mi blocks.

    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128Mi (134, 217,728) blocks. GT.M versions V5.0-000 through V5.3-003 can access databases created with V5.3-004 and later as long as they remain within a 128Mi block limit.

    • Database created with V6.0-000 or above have a maximum size of 1,040,187,392(992Mi) blocks.

    • For information on downgrading a database upgraded from V6 to V5, refer to: Downgrading to V5 or V4.

    Stage 3: Replication Instance File Upgrade

    V6.3-001A does not require new replication instance files if you are upgrading from V5.5-000. However, V6.3-001A requires new replication instance files if you are upgrading from any version prior to V5.5-000. Instructions for creating new replication instance files are in the Database Replication chapter of the GT.M Administration and Operations Guide. Shut down all Receiver Servers on other instances that are to receive updates from this instance, shut down this instance Source Server(s), recreate the instance file, restart the Source Server(s) and then restart any Receiver Server for this instance with the -UPDATERESYNC qualifier.

    [Note] 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.

    [Important] Important

    You must always follow the steps described in the Database Replication chapter of the GT.M Administration and Operations Guide when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

    Stage 4: Journal Files Upgrade

    On every GT.M upgrade:

    • Create a fresh backup of your database.

    • Generate new journal files (without back-links).

    [Important] Important

    This is necessary because MUPIP JOURNAL cannot use journal files from a release other than its own for RECOVER, ROLLBACK, or EXTRACT.

    Stage 5: Trigger Definitions Upgrade

    If you are upgrading from V5.4-002A/V5.4-002B/V5.5-000 to V6.3-001A and you have database triggers defined in V6.2-000 or earlier, you need to ensure that your trigger definitions are wholesome in the older version and then run MUPIP TRIGGER -UPGRADE. If you have doubts about the wholesomeness of the trigger definitions in the old version use the instructions below to capture the definitions delete them in the old version (-*), run MUPIP TRIGGER -UPGRADE in V6.3-001A and then reload them as described below.

    You need to extract and reload your trigger definitions only if you are upgrading from V5.4-000/V5.4-000A/V5.4-001 to V6.3-001A or if you find your prior version trigger definitions have problems. For versions V5.4-000/V5.4-000A/V5.4-001 this is necessary because multi-line XECUTEs for triggers require a different internal storage format for triggers which makes triggers created in V5.4-000/V5.4-000A/V5.4-001 incompatible with V5.4-002/V5.4-002A/V5.4-002B/V5.5-000/V6.0-000/V6.0-001/V6.3-001A.

    To extract and reapply the trigger definitions on V6.3-001A using MUPIP TRIGGER:

    1. Using the old version, execute a command like mupip trigger -select="*" trigger_defs.trg. Now, the output file trigger_defs.trg contains all trigger definitions.

    2. Place -* at the beginning of the trigger_defs.trg file to remove the old trigger definitions.

    3. Using V6.3-001A, run mupip trigger -triggerfile=trigger_defs.trg to reload your trigger definitions.

    To extract and reload trigger definitions on a V6.3-001A replicating instance using $ZTRIGGER():

    1. Shut down the instance using the old version of GT.M.

    2. Execute a command like mumps -run %XCMD 'i $ztrigger("select")' > trigger_defs.trg . Now, the output file trigger_defs.trg contains all trigger definitions.

    3. Turn off replication on all regions.

    4. Run mumps -run %XCMD 'i $ztrigger("item","-*") to remove the old trigger definitions.

    5. Perform the upgrade procedure applicable for V6.3-001A.

    6. Run mumps -run %XCMD 'if $ztrigger("file","trigger_defs.trg")' to reapply your trigger definitions.

    7. Turn replication on.

    8. Connect to the originating instance.

    [Note] Note

    Reloading triggers renumbers automatically generated trigger names.

    Downgrading to V5 or V4

    You can downgrade a GT.M V6 database to V5 or V4 format using MUPIP DOWNGRADE.

    Starting with V6.0-000, MUPIP DOWNGRADE supports the -VERSION qualifier with the following format: 

    MUPIP DOWNGRADE -VERSION=[V5|V4]

    -VERSION specifies the desired version for the database header.

    To qualify for a downgrade from V6 to V5, your database must meet the following requirements:

    1. The database was created with a major version no greater than the target version.

    2. The database does not contain any records that exceed the block size (spanning nodes).

    3. The sizes of all the keys in database are less than 256 bytes.

    4. There are no keys present in database with size greater than the Maximum-Key-Size specification in the database header, that is, Maximum-Key-Size is assured.

    5. The maximum Record size is small enough to accommodate key, overhead, and value within a block.

    To verify that your database meets all of the above requirements, execute MUPIP INTEG -NOONLINE. Note that the integrity check requires the use of -NOONLINE to ensure no concurrent updates invalidate the above requirements. Once assured that your database meets all the above requirements, MUPIP DOWNGRADE -VERSION=V5 resets the database header to V5 elements which makes it compatible with V5 versions.

    To qualify for a downgrade from V6 to V4, your database must meet the same downgrade requirements that are there for downgrading from V6 to V5.

    If your database meets the downgrade requirements, perform the following steps to downgrade to V4:

    1. In a GT.M V6.3-001A environment:

      1. Execute MUPIP SET -VERSION=v4 so that GT.M writes updates blocks in V4 format.

      2. Execute MUPIP REORG -DOWNGRADE to convert all blocks from V6 format to V4 format.

    2. Bring down all V6 GT.M processes and execute MUPIP RUNDOWN -FILE on each database file to ensure that there are no processes accessing the database files.

    3. Execute MUPIP DOWNGRADE -VERSION=V4 to change the database file header from V6 to V4.

    4. Restore or recreate all the V4 global directory files.

    5. Your database is now successfully downgraded to V4.

    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 a system that does not have ICU 3.6 or later installed, GT.M only supports M mode.

    On a system that has ICU installed, GT.M optionally 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 it finds both a source and an object file, and the object predates the source file and was generated with the same setting of $gtm_chset/$ZCHset. A GT.M process generates 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 UTF-8 mode in the utf8 subdirectory, and one compiled without support for UTF-8 mode in the parent directory. Installing GT.M generates both versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed, and you choose the option to install Unicode support. Note that on 64-bit versions of GT.M, the object code is in shared libraries, rather than individual files in the directory.

    • 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 file gtmprofile, 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_V6.3-001A_i686, then gtmprofile sets $gtm_dist to /usr/lib/fis-gtm/gtm_V6.3-001A_i686/utf8).

        • On platforms where the object files have not been placed in a libgtmutil.so shared library, 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. On platforms where the object files are in libgtmutil.so, that shared library is the one with the object files compiled in the mode for the process.

    For more information on gtmprofile, refer to the Basic Operations chapter of GT.M Administration and Operations Guide.

    Although GT.M uses ICU for UTF-8 operation, ICU is not FIS software and FIS does not support ICU.

    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.

    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or fail to position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on your specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    • GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis:

      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1),key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    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.

    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 as that provided by zlib.

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

    By default, GT.M searches for the libz.so shared library 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) or LD_LIBRARY_PATH (GNU/Linux) includes the directory containing 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.

    Although GT.M uses a library such as zlib for compression, such libraries are not FIS software and FIS does not support any compression libraries.

    Change History

    V6.3-001A

    Fixes and enhancements specific to V6.3-001A:

    Id

    Prior Id

    Category

    Summary

    GTM-8632

    -

    Other

    On Linux, an environment variable to help manage core file generation [!New Feature!]

    GTM-8685

    -

    DB

    Forward Rollback Consistency with Journal Renaming

    GTM-8700

    -

    DB

    Fixes to issues related to statistics sharing

    GTM-8702

    -

    DB

    Always ensure before images when needed in TP allocations

    GTM-8705

    Language

    ZSHOW/ZWRITE work correctly even if they result in a garbage collection

    V6.3-001

    Fixes and enhancements specific to V6.3-001:

    Id

    Prior Id

    Category

    Summary

    GTM-4283

    S9C04-002078

    Other

    GT.M accepts routines with "DOS-style" terminators [!New Feature!]

    GTM-5206

    S9D12-002397

    DB

    If possible, avoid journal file hardening when holding a database critical section

    GTM-6037

    C9H07-002874

    DB

    Reporting of numeric subscripts in globals which should not use them

    GTM-6085

    C9H10-002922

    Other

    Update Process Reader Helper avoids rare abnormal termination

    GTM-6332

    C9J01-003085

    Other

    Code generation cleanup on Linux

    GTM-6598

    C9K04-003268

    Admin

    Limit the time MUPIP BACKUP and INTEG wait for kill-in-progress to clear

    GTM-6699

    D9K10-002792

    DB

    Opt-in facility for statistics sharing [!New Feature!]

    GTM-6793

    C9L04-003395

    Language

    Limit MERGE into an lvn to 31 subscripts

    GTM-6838

    C9L06-003425

    DB

    Asynchronous database IO [!New Feature!]

    GTM-7593

    -

    Admin

    More reliable journal flushing in edge cases under replication

    GTM-7729

    -

    Admin

    LOCKs have separate resource management by default, but you can select shared resource management [!New Feature!]

    GTM-7778

    -

    Other

    More consistent timestamps on AIX gtmsecshr messages

    GTM-7837

    -

    Admin

    MUPIP REPLICATE -CHANGELOG waits for up to 25 seconds to confirm a change log request

    GTM-7857

    -

    DB

    Reporting of empty-string subscripts that conflict with database settings

    GTM-7922

    -

    Admin

    MUPIP EXTRACT protects against concurrent updates to region spanning updates

    GTM-8254

    -

    Language

    USE command accepts [I|O]CHSET for Sequential Disks, SOCKETs and terminals [!New Feature!]

    GTM-8357

    -

    Language

    GT.M initializes the value of $ZSTEP from the environment variable $gtm_zstep if it is defined

    GTM-8359

    -

    Language

    More general support for indirect arguments to TSTART commands and an explicit error for TSTART in direct mode

    GTM-8362

    -

    Admin

    Allow updates during a MUPIP FREEZE

    GTM-8366

    -

    Language

    Clear $REFERENCE after an error in a global reference

    GTM-8373

    -

    Admin

    Accept rapid changes to replication logs destination files

    GTM-8385

    -

    Language

    Computations using literals largely performed at compile time [!New Feature!]

    GTM-8427

    -

    Language

    $ZCOLLATE() converts a GVN and $ZATRANSLATE() an expression to a key representation and back [!New Feature!]

    GTM-8430

    -

    Other

    Improvement in critical section acquisition for x86_64 Linux

    GTM-8447

    -

    Admin

    MUPIP DUMPFHEAD provides lighter weight and less problematic access to database state information [!New Feature!]

    GTM-8542

    -

    Admin

    MUPIP LOAD -FORMAT=Binary validates keys in the extract records

    GTM-8544

    -

    Other

    Timer interrupt reduction

    GTM-8553

    -

    DB

    Eliminate an interaction between poollimit and extended global references

    GTM-8559

    -

    Language

    $gtm_etrap and $gtm_trigger_etrap accept 8192 byte strings [!New Feature!]

    GTM-8561

    -

    Other

    Deal appropriately with M process data exceeding 2GiB

    GTM-8562

    -

    Other

    The configure install script creates routine directories even when reusing an existing directory

    GTM-8564

    -

    Admin

    Protect an interrupted MUPIP REORG -ENCRYPT from an intervening MUPIP REORG -TRUNCATE

    GTM-8567

    -

    Other

    configure script defaults locale to allow a UTF-8 installation to proceed

    GTM-8568

    -

    Language

    Fix three rare trigger update issues

    GTM-8569

    -

    Other

    Prevent rare duplicate messages when the number of processes in an instance exceeds 32ki

    GTM-8570

    -

    Other

    Eliminate superfluous literals from object modules

    GTM-8571

    -

    Other

    Fix regression in ^%GI for GO format containing any empty data values

    GTM-8572

    -

    Language

    Prevent instances of pre-evaluation in $SELECT()

    GTM-8573

    -

    Language

    Compiler optimization for IF <literal> and command postconditional literals [!New Feature!]

    GTM-8578

    -

    Other

    Correct handling of non-char arrays in %PEEKBYNAME()

    GTM-8579

    -

    Language

    Operator optimizations at compile time [!New Feature!]

    GTM-8582

    -

    Admin

    Appropriate Source Server startup with Sync I/O and 4KiB sector sizes on an XFS filesystem

    GTM-8583

    -

    Language

    Prevent inappropriate MAXNRSUBSCRIPTS errors from MERGE

    GTM-8584

    -

    Language

    Prevent GTMASSERT caused by a <NUL> character generating a NOCANONICNAME error message

    GTM-8590

    -

    Language

    Certain timed operations deferred during $ZCONVERT()

    GTM-8593

    -

    Language

    OPEN of an existing SOCKET device can modify ZFF & delimiters; also $KEY is always in UTF-8 [!New Feature!]

    GTM-8595

    -

    Language

    Fix to M mode handling of non-ASCII literals

    GTM-8597

    -

    DB

    Better protection against one type of random error

    GTM-8598

    -

    Other

    Certain operations deferred while processing character input

    GTM-8599

    -

    Admin

    Correct odd case for MUPIP JOURNAL -ROLLBACK -FORWARD

    GTM-8602

    -

    Other

    MUPIP JOURNAL accepts multiple EOF records

    GTM-8609

    -

    Admin

    Improved error messaging for errors that occur during the first access of a journal file

    GTM-8610

    -

    Admin

    The Receiver Server avoids rare situations that could cause it to exit

    GTM-8612

    -

    Admin

    MUPIP LOAD handles minimal headers and long lines gracefully

    GTM-8613

    -

    DB

    Protect against concurrent creation of global variable with differing collation characteristics

    GTM-8614

    -

    Admin

    REQROLLBACK message indicates required -ROLLBACK also requires -NOONLINE

    GTM-8615

    -

    Other

    Certain timed operations deferred during external calls

    GTM-8629

    -

    Admin

    MUPIP RESTORE treats truncated input as an error

    GTM-8637

    -

    Other

    Prevent GTMASSERT2 from very long running jobs performing TP transactions

    GTM-8639

    -

    Language

    ZSHOW "G" provides Block Transition to Dirty (BTD) statistic for BG databases [!New Feature!]

    GTM-8640

    -

    Language

    Accept <NUL> characters in literals use for indirection and XECUTE

    GTM-8641

    -

    DB

    $ORDER(,-1) of global variables that span database blocks returns correct result

    GTM-8642

    -

    Other

    Prevent rare inappropriate GTMASSERT2 from MUPIP STOP of a process while changing encryption keys

    GTM-8645

    -

    Other

    Improved (but imperfect) tracking of database reference count

    GTM-8654

    -

    Admin

    Revised permission handling when determining group membership [!New Feature!]

    GTM-8655

    -

    DB

    Improved database structural integrity protection against kill -9

    GTM-8656

    Admin

    Support for OpenSSL 1.1.0

    GTM-8657

    -

    Admin

    Replication from BC to SI handles multiple connections with no intervening updates

    GTM-8659

    -

    Other

    Better file cleanup in case of abnormal termination during file creation

    GTM-8660

    -

    Admin

    Improved System Profiling for x86_64 Linux editions

    GTM-8664

    -

    DB

    Defer idle epoch while holding journal pool critical section lock.

    GTM-8668

    -

    Admin

    Simplify GPG Agent interaction with the encryption reference implementation

    GTM-8672

    -

    Language

    Adjustments to improve the memory utilization for heap space (primarily local variable storage)

    GTM-8676

    -

    Other

    Fix to DSE FIND -KEY

    GTM-8679

    -

    Language

    Global name-level $ORDER() maintains $REFERENCE

    GTM-8686

    -

    Other

    ^%TI works as documented

    GTM-8687

    -

    DB

    GT.M properly handles loading successive global directories with increasing numbers of regions

    GTM-8689

    -

    Language

    Protect OPEN command against external actions

    Database

    • V63-001 GT.M defers the hardening (fsync) of a journaled database file (a potentially time consuming operation) to occur as much as possible outside the database critical section, particularly when it is time to write an EPOCH record in the journal file. Previously, this was done while holding the critical section which could affect database transaction throughput. (GTM-5206)

    • V63-001MUPIP INTEG, DSE INTEG and in some instances VIEW "GDSCERT" produce a NONUMSUBS error if they encounter a numeric subscript in a global variable tree that has been defined to only use string subscripts; previously, they did not report this issue. (GTM-6037)

    • V63-001 GT.M provides a fast and efficient mechanism for processes to share their database access statistics for other processes to monitor. In addition GT.M now supports implicit instantiation of a database file. Please refer to the Additional_Information section for the details and implications of this feature. (GTM-6699) [!New Feature!]

    • V63-001 Released as field test grade functionality in a production release, asynchronous IO is an option for database segments using the BG access method; previously GT.M performed only synchronous I/O through the file system cache. Also, when invoked from the shell, GDE returns a non-zero status in case it terminates with errors; previously it always returned a zero status, even if it encountered errors. Note: when invoked from GT.M, GDE does not return a status. MUPIP RUNDOWN appropriately manages the FTOK semaphore associated with a database to which it has read-only access; previously it inappropriately removed that semaphore if the database was quiescent but its attachment counter had ever exceeded 32Ki simultaneous processes. Please refer to the Additional Information section for details. (GTM-6838) [!New Feature!]

    • V63-001 When MUPIP INTEG, DSE INTEG -BLOCK, or VIEW "GDSCERT":1 processing encounter an empty-string ("null") subscript that does not match current file header settings for the null characteristic they issue a DBNULCOL or NULLSUBS error. If MUPIP LOAD-FORMAT=BINARY encounters empty-string subscripts in an extract it is loading on a database that does not permit such subscripts, it produces a NULLSUBS error. Previously, these functions did not report these errors (MUPIP LOAD did not load the offending data). Also, if MUPIP LOAD -FORMAT=BINARY encounters two keys that are the same except for their representations of empty string subscripts, it produces a warning message and discards the one whose representation does not match that of the database into which the data is being loaded. (GTM-7857)

    • V63-001 Extended references work correctly when poollimit is enabled. Previously, such a combination could produce GTMASSERT failures. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8553)

    • V63-001 GT.M protects itself against one type of random error in a control field used for buffer management. Previously, recovery required shutting the database down. The error observed most likely resulted from some sort of hardware malfunction. Note that FIS recommmends the use of ECC RAM in production systems. (GTM-8597)

    • V63-001 GT.M issues a ACTCOLLMISMTCH error in case multiple processes concurrently attempt to create the first global node of a global variable using differing collation characteristics (defined through the -GBLNAME section of their respective global directories). Previously, it was possible for processes to proceed to update with conflicting views of the global's collation, resulting in global nodes with misaligned collation sequences in the same global, creating an application level data integrity error. This issue was only observed in the GT.M development environment, and was never reported by a user.(GTM-8613)

    • V63-001 $ORDER(gvn,-1) and $ZPREVIOUS(gvn) work correctly in case of spanning nodes. Since GT.M V6.2-002, due to a regression introduced in GTM-7917, it could return the same value as the last subscript in the input key in case the global corresponding to gvn contained spanning nodes. For example if ^X(3) existed and was a spanning node, $ORDER(^X(4),-1) would return 4 instead of 3, potentially leading to infinite loops. If ^X(3) was not a spanning node, $ORDER() would return the correct value. The return value was unaffected by the existence or non-existence of a subtree of ^X(3). (GTM-8641)

    • V63-001 GT.M does better in maintaining database integrity in the face of a kill -9 of a process in the middle of a database commit. Previously, if a process trying to update a particular GDS block was killed in the middle of a commit, it was possible to lose prior updates to just that block within the same epoch, resulting in a database file with structural damage. Note that FIS continues to strongly recommend against kill -9 of processes that have opened a database file. (GTM-8655)

    • V63-001 GT.M defers performing an idle epoch if it concurrently holds the journal pool critical section lock. Previously, under rare conditions, performing the idle epoch in this situation could result in database deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8664)

    • GT.M marks journal files as current or not current, which allows it to deal more appropriately with an operational situation in which an operator renamed an older journal file as current. Previously, GT.M MUPIP ROLLBACK -FORWARD could not detect this operational issue and consequently failed to deliver a consistent state at completion. (GTM-8685)

    • V63-001 GT.M now properly handles loading multiple global directories with increasing numbers of regions. Previously, this could have resulted in memory corruption if a process first opened the first global directory with fewer regions AND both global directories had at least one global variable name that spanned multiple regions. This issue was never reported by users and was only seen in the GT.M development environment. (GTM-8687)

    • Operations on statistics database files (e.g. VIEW "STATSHARE", VIEW "NOSTATSHARE", direct access to ^%YGS global nodes) work correctly even in the case a process accesses the same statistics database file through more than one global directory. In GT.M V6.3-001, this could cause the process to terminate abnormally with a segmentation violation (SIG-11). GT.M correctly creates statistics database files (which are always created dynamically) even in case of heavy database contention amongst processes. In GT.M V6.3-001, if a process in a TP transaction (TSTART/TCOMMIT fence) was in its final retry (due to restarts from other concurrently running processes), it was rare but possible to encounter a deadlock. $ZPEEK issues a BADZPEEKARG error when its argument specifies a non-existent lower-case region name. In GT.M V6.3-001, this terminated the process with a segmentation violation (SIG-11). MERGE, ZWRITE, $DATA(), $ORDER(), and $QUERY() involving ^%YGS open any implicitly associated statistics database files when run outside of a TP transaction. In GT.M V6.3-001, they could ignore ^%YGS nodes corresponding to regions previously unopened or untracked by the process. Note that these operations within an explicit TP transaction do not implicitly open any not-yet-open statistics database until after the transaction commits. GT.M correctly handles a MUPIP SET -REPLICATION=ON for a region which was still replicating after journaling turned off (in the "was_on" state). In GT.M V6.3-001, due to a regression introduced by GTM-7593, an exiting process executing in a small window of instructions in database rundown logic could, in rare, cases terminate with a segmentation violation (SIG-11). MUPIP SET JOURNAL and MUPIP REPLICATE -INSTANCE_CREATE issue appropriate errors when their input attempts to create journal and/or replication-instance file names whose absolute path is more than 255 bytes long. Previously, it was possible for these commands to abnormally terminate with a "stack smashing detected" error due to GT.M-internal buffer overflows. All these issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8700)

    • Updates within explicit (TSTART/TCOMMIT) or implicit (spanning nodes or regions, or triggers) transactions requiring one or more additional blocks reliably write before images (if configured) to the journal file or to a MUPIP BACKUP -ONLINE. Missing before images could cause incorrect or damaged databases after a MUPIP JOURNAL -RECOVER or -ROLLBACK, or in a backup. In GT.M V6.3-001, due to a flaw in GTM-8637, in rare cases when choosing a previously freed block, GT.M failed to appropriately write a before image. This issue were only observed in the GT.M development environment, and was never reported by a user.(GTM-8702)

    Language

    • V63-001 MERGE into a local variable (lvn) target limits the number of target subscripts to the maximum number supported by GT.M (currently 31); previously, MERGE could produce variables with 32 subscripts which could cause subsequent problems. (GTM-6793)

    • V63-001 The USE command accepts [I|O]CHSET as valid deviceparameters. It is possible to change the character set of an open device. In addition to USE, the OPEN command also changes the character set of an already opened device including Sequential Disk, SOCKET and terminal devices. It is useful to deal with binary data intermixed with character data. Previously, there was no documented way to change the character set of an open device. (GTM-8254) [!New Feature!]

    • V63-001 GT.M takes the initial value of $ZSTEP from the environment variable gtm_zstep, with a default value of "B" (a BREAK command) if gtm_zstep is not defined; previously, changing the default value required a SET command. (GTM-8357)

    • V63-001 TSTART commands with indirect arguments work correctly in GT.M. Previously, they allowed only specification of a single local variable with no parentheses, SERIAL flag or transaction id parameter. Also, use of TSTART in direct mode is prohibited and generates a NODMTSTART error. Previously, TSTART/TCOMMIT sometimes worked when on the same direct mode command line but more often got strange errors and caused memory leaks at best. (GTM-8359)

    • V63-001 GT.M assigns an empty string to $REFERENCE when there is an error while constructing a subscripted global variable. Previously, GT.M assigned the last successful subscripted global variable to $REFERENCE. (GTM-8366)

    • V63-001 GT.M performs arithmetic operations involving only literals at compile time, with the exception of divide and integer divide (/ and \) by zero (0), which because of their use to intentionally produce an error is left to run time. Note that modulo (#) produces a compile time error. Previously, GT.M did all such calculations at run-time. (GTM-8385) [!New Feature!]

    • V63-001 $ZCOLLATE(glvn,intexpr[,{0|1}]) returns a transformed representation of a first argument glvn using the alternative transform specified by the second argument intexpr that, by default, or if the optional third argument is zero (0), represents a normalized form that can be used as an operand to the follows (]) or sorts-after operator ([[) such that, if both operands are in the normalized form, the result is independent of alternative collation. If the optional third argument is non-zero, $ZCOLLATE() returns a reverse transform of the first argument intended to restore the normalized form to the native M glvn representation. $ZCOLLATE() replaces the "YGVN2GDS" and "YGDS2GVN" arguments to $VIEW(), which are deprecated. $ZATRANSFORM(expr,intexpr[,{0|1}][,{0|1}]) returns a transformed representation of a first argument expr, treated as a subscripted or unsubscripted key, using the alternative transform specified by the second argument intexpr in a normalized form that can be used as an operand to the follows (]) or sorts-after (]]) operator such that, if both operands are in the normalized form, the result is independent of alternative collation. If the optional third argument is non-zero, $ZATRANSFORM() returns a reverse transform of the first argument intended to restore a normalized form to the native M expr representation. By default, or if the optional fourth argument is zero, $ZATRANSFORM()returns the transformation of expr using standard M collation of numbers before strings, causing numbers to sort like strings; if the optional third argument is non-zero, $ZATRANSFORM() treats all expressions as strings.(GTM-8427) [!New Feature!]

    • V63-001 $gtm_etrap and $gtm_trigger_etrap accept up to 8192 bytes and produce a LOGTOOLONG message in the syslog when ignoring a value longer than 8192. Previously, process initialization limited both environment variables to 4096 bytes and did not log any message for an over-length $gtm_trigger_etrap. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8559) [!New Feature!]

    • V63-001 $ZTRIGGER() operations that affect triggers executed in the same transaction work as documented. Previously, in rare situations, transactions that performed $ZTRIGGER() operations in some, but not all, retries and invoked a trigger affected by the $ZTRIGGER() operation in some, but not all, retries could result in a TRIGDEFBAD or SIG-11. Also, trigger load operations in which an error occurred only perform a validity check on trigger delete by name operations. Previously, if an error occurred during a trigger load, a subsequent trigger delete by name operation resulted in a TRIGDEFBAD if the name targeted a trigger installed as part of the current load operation. In addition, concurrent MUPIP REORG works appropriately with GT.M triggers. Previously, in rare situations, a concurrent MUPIP REORG could cause GT.M trigger operations to issue TRIGDEFBAD errors. These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8568)

    • V63-001 $SELECT() does not pre-evaluate any expressions. A regression introduced in V6.2-002A related to GTM-8376 resulted in inappropriate pre-evaluation of arguments in some cases, especially when both FULL_BOOLEAN and gtm_side_effects modes were off. This caused inappropriate behavior such as errors in $SELECT() formulations intended to prevent execution of inappropriate indirection or $INCREMENT() acting on a global variable. (GTM-8572)

    • V63-001 When the argument of an IF command is a literal value or expression, the GT.M compiler generates code to set $TEST appropriately and ignores the rest of the line. When the argument of a command postconditional is a literal value or expression, the GT.M compiler evaluates the postconditional and either generates code for an unconditional command or omits generation for the command. Previously, the computation was performed at run time. Note that literal postconditionals evaluating to 0 result in smaller object modules than literal postconditionals evaluating to non-zero values. (GTM-8573) [!New Feature!]

    • V63-001 As part of compilation, GT.M optimizes unary operations, and binary operations, where both operands are literals; cases where the first operand is an empty string, divide and integer divide (/ or \) by zero (0) are exceptions. In addition, it treats $ZCHSET and $ZVERSION as compile time constants. Please observe the following cautions: ensure you compile with the same GT.M version, $gtm_chset, $gtm_local_collate, $gtm_patnumeric, $gtm_pattern_file and $gtm_pattern_table values (or lack thereof) as those used to run your application, and use variable operands, indirection or XECUTE for operands used with pattern match (?) or sorts-after (]]) if the application changes the run time values controlled by those environment variables. Note that the compiler detects a few errors at slightly different points which may change some messages, hopefully for the better. In addition, this change prevents a possible segmentation violation (SIG-11) in V6.3-000[A] when attempting to MUMPS -RUN of a routine with no current object module when the routine uses ZWRITE. (GTM-8579) [!New Feature!]

    • V63-001 MERGE permits its target to hold the maximum number of subscripts supported by GT.M (currently 31). Beginning with V6.1-000 the change associated with GTM-7867 could cause inappropriate MAXNRSUBSCRIPTS errors when the source and the target were both global variables, most likely when the source had many subscripts. The workaround was to MERGE the source into a local variable and then MERGE from there to the actual target. (GTM-8583)

    • V63-001 $QLENGTH(), $QSUBSCRIPT() and $ZCOLLATE() use ZWRITE format to report the namevalue in any NOCANONICNAME error. Previously, a <NUL> byte in the input resulted in a GTMASSERT. (GTM-8584)

    • V63-001 GT.M defers certain timed operations while performing a $ZCONVERT(); previously, the function could hang if interrupted by an timed operation that invoked non-reentrantsystem memory management services. This issue was only observed in the GT.M development environment, and was never reported by a user.(GTM-8590)

    • V63-001 Deviceparameters on the OPEN command for SOCKET device containing open sockets can modify the ZFF and delimiters of the current socket; previously, these could only be changed with a USE command. In addition, $KEY and $ZB for SOCKET devices appropriately return UTF-8 representations of the characters; previously, if the device character set was UTF-16[BE|LE], the terminator representations were inappropriately also encoded in UTF-16[BE|LE]. (GTM-8593) [!New Feature!]

    • V63-001 In M mode, $ASCII() of literal characters returns the correct value. In V6.3-000/-000A, this returned an incorrect value, typically -1 (it worked correctly for ASCII literal characters, for variable arguments, and in UTF-8 mode). Note that this is an edge case: instead of coding $ASCII() of a literal, one would normally just use the value, e.g., 65 instead of $ASCII("A"), and furthermore, the supported character set for literals in M programs is a subset of ASCII, whereas the issue affected literals corresponding to the non-ASCII characters $CHAR(128) through $CHAR(255). (GTM-8595)

    • V63-001 ZSHOW "G" and $VIEW("GVSTAT") report a count BTD, which for database regions that use the BG access method is the number of times a global buffer has transitioned from an clean (unmodified) state to a dirty (modified) state. For database regions that use the MM access method, BTD is zero. (GTM-8639) [!New Feature!]

    • V63-001 GT.M accepts NUL characters ($CHAR(0)) within literals used in indirection and XECUTE; previously, it generated errors for that character. (GTM-8640)

    • V63-001GT.M now reduces the active memory usage when a process uses a large amount of memory then subsequently uses a significantly reduced amount. Previously, active memory usage was distributed across the whole memory segment. In addition, $VIEW("SPSIZE") now returns three sizes (as comma separated values): the total amount of space allocated to the heap, amount of heap space in use, and amount of heap space reserved. The reserved space is used to reduce the active memory usage as mentioned above. GT.M now extends memory used for local variables more frequently when garbage collection does not reclaim a significant amount of space.(GTM-8672)

    • V63-001 Name-level $ORDER() on globals maintains $REFERENCE analogously to other $ORDER() invocations, that is: by reflecting the first argument unless a subsequent global reference in the second argument takes precedence; previously, it left $REFERENCE empty except when the second argument was a variable. This also applies to $ZPREVIOUS(), which is a deprecated way to do a $ORDER(,-1). (GTM-8679)

    • V63-001 GT.M protects OPEN commands against the possibility they don't complete due to an interrupt or device failure; previously, there was a very small window where external actions such as <CTRL-C>, MUPIP INTRPT, or a device disconnect could leave a device partially set up, which could cause a subsequent segmentation violation (SIG-11). This was only encountered in the GT.M development environment and was never reported by a user. (GTM-8689)

    • ZSHOW/ZWRITE work correctly even if they encounter a relatively rare heap management action. Previously, these commands could terminate with a segmentation violation (SIG-11) in these rare cases. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8705)

    System Administration

    • V63-001 MUPIP BACKUP and INTEG wait approximately one minute for any kill-in-progress to clear. Previously, the times exceeded the documented one minute time by three times for INTEG and an amount for BACKUP that was a function of the number of regions with kill-in-progress indicators; abandoned indicators showed this issue most strongly. These problems were never reported by users and were only seen in the GT.M development environment. (GTM-6598)

    • V63-001 GT.M flushes dirty journal and database buffers to disk in a timely manner in a replicated environment. Additionally, the Source Server recovers from an unflushed journal buffer situation by taking on the task of flushing, if needed, every eight (8) seconds while waiting for a journal record in the journal file. It logs a "REPL_INFO : Source server did flush of journal file" message to record such an event. Previously, it was possible in a rare case, involving journal file switches and process exits, for the buffers to stay unflushed causing the Source Server to issue a "REPL_WARN: Check for problems with journaling" alert every 50 seconds. The workaround for this situation was to start a new process that did an update or shut the source server down. (GTM-7593)

    • V63-001GDE ADD, CHANGE and TEMPLATE for REGION objects recognize the -[NO]LOCK_CRIT qualifier; MUPIP SET recognizes a -[NO]LCK_SHARES_DB_CRIT qualifier. Both control whether LOCK actions share the same resource and management as the database or use a separate resource and management. The GDE choice only affects database file creation with MUPIP CREATE. GDE SHOW -ALL and -REGION, and DSE DUMP -FILEHEADER each display the choice, which defaults to Sep(arate)/FALSE. Previously LOCK actions used the same resource and manager. While we expect this to have either no effect or a positive effect on performance depending on the application use patterns, it is different by default, so you should be aware of this change. (GTM-7729) [!New Feature!]

    • V63-001 MUPIP REPLICATE -CHANGELOG waits for up to twenty-five seconds for confirmation from Source and Receiver Server processes that the change succeeded (it may not for a variety of reasons). Previously, only MUPIP REPLICATE -RECEIVER -CHANGELOG waited; MUPIP REPLICATE -SOURCE -CHANGELOG did not. (GTM-7837)

    • V63-001 MUPIP EXTRACT appropriately handles the case where a concurrent process updates a spanning node that MUPIP EXTRACT is processing; previously, this situation could cause a segmentation violation (SIG-11). Note that running an EXTRACT without -FREEZE and with concurrent activity produces an inconsistent output (GTM-7922)

    • V63-001MUPIP FREEZE -ON -ONLINE freezes updates to the database file, but allows updates to memory and journal files to continue. As for normal freezes, the Online Freeze is removed by a MUPIP FREEZE -OFF. Online Freeze may only be used on regions with the BG access method.

      In the Online Freeze state, GT.M prevents casual database updates from occurring, including background flushing and timed epochs. However, certain conditions require updates to the database file, including full database buffers, journal file switches, and database file extensions. The -[NO]AUTORELEASE option may be used with the -ON option to select the behavior in these conditions, with -AUTORELEASE being the default. If a GT.M process autoreleases an Online Freeze, it sends an OFRZAUTOREL message to the operator log, all processes will be allowed to write to the database file, and a subsequent MUPIP FREEZE -OFF will warn that an Online Freeze had been removed. In this case any database copy or snapshot should be considered suspect and retried. If -NOAUTORELEASE is specified, memory updates will be suspended rather than release the freeze. If a process encounters this situation while holding a critical resource, it will send an OFRZCRITSTUCK message to the operator log and wait, which will prevent other operations on the region. When the Online Freeze is removed by a MUPIP FREEZE -OFF, the waiting process will send a OFRZCRITREL message to the operator log.

      Some commands which cannot run with an Online Freeze, e.g., MUPIP BACKUP and MUPIP SET -JOURNAL, will either autorelease or issue an OFRZACTIVE error, depending on the -[NO]AUTORELEASE option used to set the freeze. Other commands, e.g., MUPIP EXTEND, MUPIP REORG -TRUNCATE, and MUPIP INTEG -ONLINE, will either autorelease or hang until the Online Freeze is released.

      A MUPIP FREEZE -OFF must always follow a MUPIP FREEZE -ON -ONLINE, even in the case of an autorelease, to ensure that normal operations are resumed. In the case of an autorelease, the MUPIP FREEZE -OFF command will report a OFRZNOTHELD warning.

      To maximize the time that updates to memory may continue, MUPIP FREEZE -ON -ONLINE flushes all dirty buffers to disk and performs a journal file switch, but it does not perform a database extension. If a database file is nearly full, the user should consider doing a database file extension before the Online Freeze. When the previous FREEZE operation was -ONLINE, a MUPIP FREEZE -OFF flushes any dirty buffers to disk and performs a journal file switch. These operations are performed in such a way as to minimize impact to processes doing memory updates, but they do involve performing epochs, so there may be some delay to other processes.(GTM-8362)

    • V63-001 MUPIP replication servers accept changes to their log file destinations immediately after the last change; previously, they occasionally required a wait between changes. (GTM-8373)

    • V63-001 MUPIP DUMPFHEAD [-FILE <file-name>][-REGION <region-list>] provides a way to get substantially the same information as DSE DUMP -FILEHEADER, but in the same format as provided by %PEEKBYNAME, and without connecting to database files. It is both lighter weight than DSE and avoids the need to use DSE, for which operator error can have serious consequences. The formatting is more regular than that of DSE. As MUPIP DUMPFHEAD does not open shared memory, values reported for dynamic fields that are in shared memory may be stale. Because MUPIP DUMPFHEAD is implemented in MUMPS, application code can call getfields^%DUMPFHEAD(varname,dbfilename), where varname is a local variable name passed by reference, and dbfilename is the name of a database file, to generate the records dumped by MUPIP. Note that this facility supersedes ^%DSEWRAP, which is deprecated, is not updated or tested, and eventually will be withdrawn. (GTM-8447) [!New Feature!]

    • V63-001 MUPIP LOAD -FORMAT=BINARY validates the keys in the extract records and reports any errors it detects before skipping the bad record and any following records in the block. Previously, LOAD of a binary extract did not validate incoming keys. (GTM-8542)

    • V63-001 MUPIP REORG -ENCRYPT works correctly when reissued after a prior invocation of the same command was interrupted. Previously, if a MUPIP REORG -TRUNCATE was run in between and did truncate the database, it was possible for the reissued MUPIP REORG -ENCRYPT to incorrectly succeed even though it did not finish the (re)encryption. This was particularly evident if one ran a MUPIP SET -ENCRYPTIONCOMPLETE command on the same database which correctly indicated the encryption as incomplete. This issue was only observed in the GT.M development environment, and was never reported by a user. A workaround for this was to run a MUPIP EXTEND on the database and reissue the MUPIP REORG -ENCRYPT. (GTM-8564)

    • V63-001 Enabling sync_io for journaling works correctly on XFS filesystems configured with 4KiB sector sizes. Previously, the Source Server could experience a REPLFILIOERR error with the message "Error in reading jfh in update_eof_addr" when reading from journal files. (GTM-8582)

    • V63-001 MUPIP JOURNAL -ROLLBACK -FORWARD correctly rolls the database forward in the case one region has a journal file with very limited update activity (less duration than the epoch interval of that region). Previously, it was possible, in the unlikely case of a crash (where the journal files were not cleanly shutdown) where a region had only a single epoch matching the safe restore time determined across all regions, for ROLLBACK to inappropriately set the database file header as if it had restored updates beyond those it actually restored, which could cause a subsequent replication restart to miss updates. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8599)

    • V63-001 The error messages for JNLTRANSLSS and JNLTRANSGTR now include the transaction numbers in the database file header and journal file header. The accompanying JNLOPNERR prints the name of the database and journal files. Previously, when issued alongside a JNLSENDOPER message, JNLOPNERR missed information about the database file, and there were no transaction numbers for JNLTRANSLSS or JNLTRANSGTR. The error JNLREADEOF omits the journal file name as the accompanying JNLEXTEND message prints this information.[/p][p]The error messages JNLBADRECFMT, JNLVSIZE, and CRYPTJNLMISMATCH include context information when a process fails to open a journal file for thefirst time. Previously, these error messages did not include some or all of the context information. (GTM-8609)

    • V63-001 The Receiver Server handles unusual protocol messages appropriately. Previously, in extremely rare circumstance, the Receiver Server could mishandle such a message and terminate with a segmentation violation or REPLTRANS2BIG error preceded by numerous "Received UNKNOWN message" messages. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8610)

    • V63-001 MUPIP LOAD does not terminate abnormally with a segmentation fault (SIG-11) when delivering the MAXSTRLEN error nor does MUPIP LOAD treat a 12 byte header as a MAXSTRLEN error. Previously, a 12 byte header line in a GO or ZWRITE extract could cause GT.M to terminate abnormally with a segmentation fault (SIG-11). The workaround for the short header was to edit it in order to pad the length. (GTM-8612)

    • V63-001 The REQROLLBACK message indicates that required -ROLLBACK also requires the -NOONLINE qualifier.(GTM-8614)

    • V63-001 MUPIP RESTORE issues an IOEOF error and exits with a non-zero status when supplied with a truncated backup file. Previously, it used to prompt for the next volume to be mounted and later issue a SYSTEM-E-UNKNOWN error and incorrectly exit with a zero status indicating normal exit. Additionally, it cleans up database semaphore ipcs in case of errors; previously left two semaphores per database in case of errors.(GTM-8629)

    • V63-001 GT.M considers available process groups when determining permissions based on group membership for IPCs and files, like journals and snapshot files. Previously, when GT.M failed to determine group membership, GT.M inappropriately removed owner access to the IPCs that it created resulting either a PERMGENFAIL error or DBFILERR error followed by the supplemental text "Error with database control semctl SETVAL". (GTM-8654) [!New Feature!]

    • V63-001 The GT.M reference encryption plugin is compatible with OpenSSL 1.1.0. Previously, the plugin would not compile with OpenSSL 1.1.0. (GTM-8656)

    • V63-001 GT.M replication appropriately handles the case where a receiving Supplementary Instance (P) connects to a non-supplementary Originating Instance (A) for the first time and then reconnects with no intervening updates. Previously, if the A->P connection occurred twice with no intervening update, replication from P to another receiving Supplementary Instance (Q) failed with a STRMSEQMISMTCH error. (GTM-8657)

    • V63-001 GT.M makes more information available to system profiling tools such as perf. [x86_64 Linux] (GTM-8660)

    • V63-001 The GT.M reference encryption plugin Makefile copies the pinentry.m routine into $gtm_dist/plugin/gtmcrypt and the GT.M reference encryption plugin pinentry program includes $gtm_dist/plugin/r in the gtmroutines search path. Previously, if the encryption plug-in source archive was not extracted in $gtm_dist/plugin/gtmcrypt, the custom pinentry program failed to load the pinentry routine and the user would be prompted via the system default pinentry program.The GT.M Encryption plugin properly compiles when GT.M is installed without Unicode support. Previously, this would result in the Makefile exiting with an error. The GT.M encryption plugin includes support for loopback pinentry mode (available starting with GnuPG 2.1.12) which simplifies unattended passphrase handling.(GTM-8668)

    Other

    • V63-001 The GT.M compiler accepts input with <CR><LF> line termination (common on some non-POSIX Operating Systems); previously, it did not. Our thanks to the membership of the May 2016 "Hacking GT.M" workshop for this change. (GTM-4283) [!New Feature!]

    • V63-001 Update Process Reader Helpers operate correctly. Previously, under rare conditions the Reader Helper would encounter a segmentation violation (SIG-11). This was only encountered in the GT.M development environment, and was never reported by a user. (GTM-6085)

    • V63-001 Code using literals on Linux on x86_64 is faster, and the generated object file is smaller than previously. Compilation is also faster, which should, in turn, speed up operations using indirection and XECUTE. As with any performance enhancement, actual benefit will vary, depending on the extent to which application code uses constructs that benefit from this change. [x86_64 Linux] (GTM-6332)

    • V63-001 The gtmsecshr wrapper on AIX uses the standard system timezone taken from /etc/environment for the timestamps of any syslog entries it generates. It also passes this timezone on to gtmsecshr to use for its entries as well. Previously, syslog timestamps from the AIX gtmsecshr wrapper could be either in the timezone of the process that started gtmsecshr or UTC, depending on whether environment variables had been cleared at the time of the error or not. [AIX] (GTM-7778)

    • V63-001 Critical section acquitions are slightly more efficient. [x86_64 Linux] (GTM-8430)

    • V63-001 GT.M manages time-related tasks in a more lightweight fashion. On heavily loaded systems with large numbers of processes, this should reduce the number of interrupts and context switches that the operating system needs to process. In addition, GT.M processes time-related tasks in a timely fashion. Previously, in rare conditions, timed operations (e.g., HANG) could be delayed up to eight seconds. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8544)

    • V63-001 A GT.M process functions correctly when its M data heap exceeds 2GiB. Previously, such a process could experience damage to internal data structures, leading to incorrect process behavior including process termination with segmentation violations (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8561)

    • V63-001 The GT.M configure installation script always creates the plug-in routine source and object file directories. Previously, when installing over an existing directory the installation script did not create the plug-in routine source and object file directories. (GTM-8562)

    • V63-001 When directed to install GT.M with UTF-8 support, the configure script defaults to the C.UTF-8 locale when systems have none defined. Previously, the configure script terminated prematurely on such a condition. This was only seen by users building GT.M from source in a restricted build environment. (GTM-8567)

    • V63-001 When starting up, the replication Receiver Server only issues a NOMORESEMCNT message to the syslog if it is the first process to determine that more than 32Ki GT.M processes have run in that instance. Previously, in very rare cases, it could inappropriately log a duplicate message. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8569)

    • V63-001 The GT.M compiler reduces the size of object modules by not placing literals in an object module once the compilation eliminates a need for them. Previously, it sometimes left obsolete literals in the object files; in V6.3-000[A], GTM-7762 made this a more significant issue. (GTM-8570)

    • V63-001 ^%GI appropriately handles empty string data values in GO format input. In V6.3-000 and V6.3-000A, ^%GI ignored such input, leading to incorrect loads. The workaround was to use ZWR format or MUPIP LOAD. (GTM-8571)

    • V63-001 ^%PEEKBYNAME() handles cases where the type of data it is to access is an array of known types by returning a comma delimited list of the array elements; for example, $$^%PEEKBYNAME("sgmnt_data.tp_cdb_sc_blkmod",base) returns a string in the form "0,0,0,0,0,0,0,0" because the arguments identify an array of 8 integers (type int). Previously, this kind of invocation produced a BADZPEEKFMT error. (GTM-8578)

    • V63-001 GT.M briefly defers certain operations while processing character input; previously, the non-reentrant system memory management services used in character-based input could hang a process if their timed operations also invoked memory management services. (GTM-8598)

    • V63-001 MUPIP JOURNAL accepts multiple EOF records in the same journal file. Multiple EOF records only occur when the last process to halt out of a journaled database terminates abnormally just before cleanly shutting down the journal file. Note that FIS strongly recommends against using kill -9 on any GT.M process performing database updates. Previously, MUPIP JOURNAL produced a GTM-E-JNLUNXPCTERR error when it encountered multiple EOF records in a journal file. (GTM-8602)

    • V63-001 GT.M prevents certain timed operations during external calls. Previously, in an environment using encrypted databases,an external call could cause the process to hang due to an invocation of non-reentrant memory management system services also invoked by the encryption plug-in. (GTM-8615)

    • The gtm_coredump_filter environment variable specifies the mappings of the process address space for a GT.M process, with the bits having the same meaning as those specified for /proc/<pid>/coredump_filter in "man 5 core". If unspecified, GT.M uses a value of 0x73; a value of -1 prevents GT.M from modifying the coredump_filter value. A running process can change its coredump_filter by writing to the file /proc/<pid /coredump_filter, and can query the current value by reading that file. [Linux x86_64] (GTM-8632)

    • V63-001 Processes handle a large volume of TP updates appropriately; previously, a long-running process, such as an Update Process, adding new global nodes could eventually inappropriately terminate with a GTMASSERT2. (GTM-8637)

    • V63-001 GT.M appropriately handles the case of a process receiving a MUPIP STOP while another process has recently been performing a MUPIP REORG -ENCRYPT to change the encryption keys. In V6.3-000[A] this combination could rarely cause the stopped process to terminate with a GTMASSERT2 error. This caused no problems for the database. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8642)

    • V63-001 GT.M more accurately maintains the count of the number of processes attached to a database file $$^%PEEKBYNAME("node_local.ref_cnt",<region>) or "Reference count" in DSE DUMP -FILE output. Note that GT.M does not rely on this field, which exists to supply operational information to the user, but which may be inaccurate if processes are subject to kill - 9 - something that FIS recommends against and that GT.M does not guard against. Previously, in case the database has the quick-rundown mode enabled (MUPIP SET -QDBRUNDOWN), this counter could become inaccurate even without interference from kill -9. (GTM-8645)

    • V63-001 When GT.M exits with a fatal error, such as GTM-F-MEMORY, it cleans up any empty file it was in the process of creating at the time of the failure. This applies to GT.M OPEN, DSE OPEN and a number of MUPIP functions which create files. Previously, this unusual situation left an empty file and in some cases the process terminated with a segmentation fault (SIG-11). (GTM-8659)

    • V63-001 DSE FIND -KEY reports the correct path leading to the input key. For versions V6.0-000 to V6.3-000A, due to a regression introduced by GTM-6341, it sometimes reported an incorrect Global tree path if the input key is not found in the database file. (GTM-8676)

    • V63-001 ^%TI works as documented; previously, it rejected some documented forms. (GTM-8686)

    More Information

    Additional information for GTM-6838 - Asynchronous database IO

    Released as field test grade functionality in a production release, asynchronous IO is an option for database segments using the BG access method; previously GT.M performed only synchronous I/O through the file system cache.

    • $$^%PEEKBYNAME("sgmnt_data.asyncio",<region-name>) - returns TRUE (1) if the region has asynchronous I/O enabled and FALSE (0) if it does not.
    • $$^%PEEKBYNAME("node_local.wcs_wip_lvl",<region-name>) - returns the number of blocks for which GT.M has issued writes that it has not yet recognized as complete.

    DSE DUMP -FILEHEADER reports the above information for a region as follows:

    • Async IO - whether AsyncIO is ON or OFF for the database
    • WIP queue cache blocks - the number of blocks for which GT.M has issued writes that it has not yet recognized as complete

    GDE ADD, CHANGE and TEMPLATE commands accept the following qualifier for SEGMENT objects with an access method of BG:

    • +tar -xvf source.tar

    • Follow the instructions in the README.

      • Open Makefile with your editor; review and edit the common header (IFLAGS) and library paths (LIBFLAGS) in the Makefile to reflect those on your system.

      • Define the gtm_dist environment variable to point to the absolute path for the directory where you have GT.M installed

      • Copy and paste the commands from the README to compile and install the encryption plugin with the permissions defined at install time

    Upgrading to GT.M V6.3-001A

    The GT.M database consists of four types of components- database files, journal files, global directories, and replication instance files. The format of some database components differs for 32-bit and 64-bit GT.M releases for the x86 GNU/Linux platform.

    GT.M upgrade procedure for V6.3-001A consists of 5 stages:

    Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V6.3-001A depends on your GT.M upgrade history and your current version.

    Stage 1: Global Directory Upgrade

    FIS strongly recommends you back up your Global Directory file before upgrading. There is no one-step method for downgrading a Global Directory file to an older format.

    To upgrade from any previous version of GT.M:

    • Open your Global Directory with the GDE utility program of GT.M V6.3-001A.

    • Execute the EXIT command. This command automatically upgrades the Global Directory.

    To switch between 32- and 64-bit global directories on the x86 GNU/Linux platform:

    1. Open your Global Directory with the GDE utility program on the 32-bit platform.

    2. On GT.M versions that support SHOW -COMMAND, execute SHOW -COMMAND -FILE=file-name. This command stores the current Global Directory settings in the specified file. .

    3. On GT.M versions that do not support GDE SHOW -COMMAND, execute the SHOW -ALL command. Use the information from the output to create an appropriate command file or use it as a guide to manually enter commands in GDE.

    4. Open GDE on the 64-bit platform. If you have a command file from 2. or 3., execute @file-name and then run the EXIT command. These commands automatically create the Global Directory. Otherwise use the GDE output from the old Global Directory and apply the settings in the new environment.

    An analogous procedure applies in the reverse direction.

    If you inadvertently open a Global Directory of an old 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 to downgrade to an old GT.M release:

    • Open the global directory with the GDE utility program of V6.3-001A.

    • Execute the SHOW -COMMAND -FILE=file-name command. This command stores the current Global Directory settings in the file-name command file. If the old version is significantly out of date, edit the command file to remove the commands that do not apply to the old format. Alternatively, you can use the output from SHOW -ALL or SHOW -COMMAND as a guide to manually enter equivalent GDE commands for the old version.

    Stage 2: Database Files Upgrade

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

    A V6 database file is a superset of a V5 database file and has potentially longer keys and records. Therefore, upgrading a database file requires no explicit procedure. After upgrading the Global Directory, opening a V5 database with a V6 process automatically upgrades fields in the database fileheader.

    A database created with V6 supports up to 992Mi blocks and is not backward compatible. V6 databases that take advantage of V6 limits on key size and records size cannot be downgraded. Use MUPIP DOWNGRADE -VERSION=V5 to downgrade a V6 database back to V5 format provided it meets the database downgrade requirements. For more information on downgrading a database, refer to Downgrading to V5 or V4.

    [Important] Important

    A V5 database that has been automatically upgraded to V6 can perform all GT.M V6.3-001A operations. However, that database can only grow to the maximum size of the version in which it was originally created. A database created on V5.0-000 through V5.3-003 has maximum size of 128Mi blocks. A database created on V5.4-000 through V5.5-000 has a maximum size of 224Mi blocks. A database file created with V6.0-000 (or above) can grow up to a maximum of 992Mi blocks. This means that, for example, the maximum size of a V6 database file having 8KiB block size is 7936GiB (8KiB*992Mi).

    [Important] Important

    In order to perform a database downgrade you must perform a MUPIP INTEG -NOONLINE. If the duration of the MUPIP INTEG exceeds the time allotted for an upgrade you should rely on a rolling upgrade scheme using replication.

    If your database has any previously used but free blocks from an earlier upgrade cycle (V4 to V5), you may need to execute the MUPIP REORG -UPGRADE command. If you have already executed the MUPIP REORG -UPGRADE command in a version prior to V5.3-003 and if subsequent versions cannot determine whether MUPIP REORG -UPGRADE performed all required actions, it sends warnings to the syslog requesting another run of MUPIP REORG -UPGRADE. In that case, perform any one of the following steps:

    • Execute the MUPIP REORG -UPGRADE command again, or

    • Execute the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command to stop the warnings.

    [Caution] Caution

    Do not run the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command unless you are absolutely sure of having previously run a MUPIP REORG -UPGRADE from V5.3-003 or later. An inappropriate DSE CHANGE -FILEHEADE -FULLY_UPGRADED=1 may lead to database integrity issues.

    You do not need to run MUPIP REORG -UPGRADE on:

    • A database that was created by a V5 MUPIP CREATE

    • A database that has been completely processed by a MUPIP REORG -UPGRADE from V5.3-003 or later.

    For additional upgrade considerations, refer to Database Compatibility Notes.

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

    You need to upgrade your database files only when there is a block format upgrade from V4 to V5. However, some versions, for example, database files 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.

    • 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.

    • Run the MUPIP REORG -UPGRADE command. This command upgrades all V4 blocks to V5 format.

    [Note] Note

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

    Database Compatibility Notes

    • Changes to the database file header may occur in any release. GT.M automatically upgrades database file headers as needed. Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.

    • Databases created with V5.3-004 through V5.5-000 can grow to a maximum size of 224Mi (234,881,024) blocks. This means, for example, that with an 8KiB block size, the maximum database file size is 1,792GiB; this is effectively the size of a single global variable that has a region to itself and does not itself span regions; a database consists of any number of global variables. A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128Mi to 224Mi blocks.

    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128Mi (134, 217,728) blocks. GT.M versions V5.0-000 through V5.3-003 can access databases created with V5.3-004 and later as long as they remain within a 128Mi block limit.

    • Database created with V6.0-000 or above have a maximum size of 1,040,187,392(992Mi) blocks.

    • For information on downgrading a database upgraded from V6 to V5, refer to: Downgrading to V5 or V4.

    Stage 3: Replication Instance File Upgrade

    V6.3-001A does not require new replication instance files if you are upgrading from V5.5-000. However, V6.3-001A requires new replication instance files if you are upgrading from any version prior to V5.5-000. Instructions for creating new replication instance files are in the Database Replication chapter of the GT.M Administration and Operations Guide. Shut down all Receiver Servers on other instances that are to receive updates from this instance, shut down this instance Source Server(s), recreate the instance file, restart the Source Server(s) and then restart any Receiver Server for this instance with the -UPDATERESYNC qualifier.

    [Note] 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.

    [Important] Important

    You must always follow the steps described in the Database Replication chapter of the GT.M Administration and Operations Guide when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

    Stage 4: Journal Files Upgrade

    On every GT.M upgrade:

    • Create a fresh backup of your database.

    • Generate new journal files (without back-links).

    [Important] Important

    This is necessary because MUPIP JOURNAL cannot use journal files from a release other than its own for RECOVER, ROLLBACK, or EXTRACT.

    Stage 5: Trigger Definitions Upgrade

    If you are upgrading from V5.4-002A/V5.4-002B/V5.5-000 to V6.3-001A and you have database triggers defined in V6.2-000 or earlier, you need to ensure that your trigger definitions are wholesome in the older version and then run MUPIP TRIGGER -UPGRADE. If you have doubts about the wholesomeness of the trigger definitions in the old version use the instructions below to capture the definitions delete them in the old version (-*), run MUPIP TRIGGER -UPGRADE in V6.3-001A and then reload them as described below.

    You need to extract and reload your trigger definitions only if you are upgrading from V5.4-000/V5.4-000A/V5.4-001 to V6.3-001A or if you find your prior version trigger definitions have problems. For versions V5.4-000/V5.4-000A/V5.4-001 this is necessary because multi-line XECUTEs for triggers require a different internal storage format for triggers which makes triggers created in V5.4-000/V5.4-000A/V5.4-001 incompatible with V5.4-002/V5.4-002A/V5.4-002B/V5.5-000/V6.0-000/V6.0-001/V6.3-001A.

    To extract and reapply the trigger definitions on V6.3-001A using MUPIP TRIGGER:

    1. Using the old version, execute a command like mupip trigger -select="*" trigger_defs.trg. Now, the output file trigger_defs.trg contains all trigger definitions.

    2. Place -* at the beginning of the trigger_defs.trg file to remove the old trigger definitions.

    3. Using V6.3-001A, run mupip trigger -triggerfile=trigger_defs.trg to reload your trigger definitions.

    To extract and reload trigger definitions on a V6.3-001A replicating instance using $ZTRIGGER():

    1. Shut down the instance using the old version of GT.M.

    2. Execute a command like mumps -run %XCMD 'i $ztrigger("select")' > trigger_defs.trg . Now, the output file trigger_defs.trg contains all trigger definitions.

    3. Turn off replication on all regions.

    4. Run mumps -run %XCMD 'i $ztrigger("item","-*") to remove the old trigger definitions.

    5. Perform the upgrade procedure applicable for V6.3-001A.

    6. Run mumps -run %XCMD 'if $ztrigger("file","trigger_defs.trg")' to reapply your trigger definitions.

    7. Turn replication on.

    8. Connect to the originating instance.

    [Note] Note

    Reloading triggers renumbers automatically generated trigger names.

    Downgrading to V5 or V4

    You can downgrade a GT.M V6 database to V5 or V4 format using MUPIP DOWNGRADE.

    Starting with V6.0-000, MUPIP DOWNGRADE supports the -VERSION qualifier with the following format: 

    MUPIP DOWNGRADE -VERSION=[V5|V4]

    -VERSION specifies the desired version for the database header.

    To qualify for a downgrade from V6 to V5, your database must meet the following requirements:

    1. The database was created with a major version no greater than the target version.

    2. The database does not contain any records that exceed the block size (spanning nodes).

    3. The sizes of all the keys in database are less than 256 bytes.

    4. There are no keys present in database with size greater than the Maximum-Key-Size specification in the database header, that is, Maximum-Key-Size is assured.

    5. The maximum Record size is small enough to accommodate key, overhead, and value within a block.

    To verify that your database meets all of the above requirements, execute MUPIP INTEG -NOONLINE. Note that the integrity check requires the use of -NOONLINE to ensure no concurrent updates invalidate the above requirements. Once assured that your database meets all the above requirements, MUPIP DOWNGRADE -VERSION=V5 resets the database header to V5 elements which makes it compatible with V5 versions.

    To qualify for a downgrade from V6 to V4, your database must meet the same downgrade requirements that are there for downgrading from V6 to V5.

    If your database meets the downgrade requirements, perform the following steps to downgrade to V4:

    1. In a GT.M V6.3-001A environment:

      1. Execute MUPIP SET -VERSION=v4 so that GT.M writes updates blocks in V4 format.

      2. Execute MUPIP REORG -DOWNGRADE to convert all blocks from V6 format to V4 format.

    2. Bring down all V6 GT.M processes and execute MUPIP RUNDOWN -FILE on each database file to ensure that there are no processes accessing the database files.

    3. Execute MUPIP DOWNGRADE -VERSION=V4 to change the database file header from V6 to V4.

    4. Restore or recreate all the V4 global directory files.

    5. Your database is now successfully downgraded to V4.

    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 a system that does not have ICU 3.6 or later installed, GT.M only supports M mode.

    On a system that has ICU installed, GT.M optionally 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 it finds both a source and an object file, and the object predates the source file and was generated with the same setting of $gtm_chset/$ZCHset. A GT.M process generates 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 UTF-8 mode in the utf8 subdirectory, and one compiled without support for UTF-8 mode in the parent directory. Installing GT.M generates both versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed, and you choose the option to install Unicode support. Note that on 64-bit versions of GT.M, the object code is in shared libraries, rather than individual files in the directory.

    • 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 file gtmprofile, 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_V6.3-001A_i686, then gtmprofile sets $gtm_dist to /usr/lib/fis-gtm/gtm_V6.3-001A_i686/utf8).

        • On platforms where the object files have not been placed in a libgtmutil.so shared library, 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. On platforms where the object files are in libgtmutil.so, that shared library is the one with the object files compiled in the mode for the process.

    For more information on gtmprofile, refer to the Basic Operations chapter of GT.M Administration and Operations Guide.

    Although GT.M uses ICU for UTF-8 operation, ICU is not FIS software and FIS does not support ICU.

    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.

    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or fail to position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on your specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    • GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis:

      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1),key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    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.

    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 as that provided by zlib.

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

    By default, GT.M searches for the libz.so shared library 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) or LD_LIBRARY_PATH (GNU/Linux) includes the directory containing 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.

    Although GT.M uses a library such as zlib for compression, such libraries are not FIS software and FIS does not support any compression libraries.

    Change History

    V6.3-001A

    Fixes and enhancements specific to V6.3-001A:

    Id

    Prior Id

    Category

    Summary

    GTM-8632

    -

    Other

    On Linux, an environment variable to help manage core file generation [!New Feature!]

    GTM-8685

    -

    DB

    Forward Rollback Consistency with Journal Renaming

    GTM-8700

    -

    DB

    Fixes to issues related to statistics sharing

    GTM-8702

    -

    DB

    Always ensure before images when needed in TP allocations

    GTM-8705

    Language

    ZSHOW/ZWRITE work correctly even if they result in a garbage collection

    V6.3-001

    Fixes and enhancements specific to V6.3-001:

    Id

    Prior Id

    Category

    Summary

    GTM-4283

    S9C04-002078

    Other

    GT.M accepts routines with "DOS-style" terminators [!New Feature!]

    GTM-5206

    S9D12-002397

    DB

    If possible, avoid journal file hardening when holding a database critical section

    GTM-6037

    C9H07-002874

    DB

    Reporting of numeric subscripts in globals which should not use them

    GTM-6085

    C9H10-002922

    Other

    Update Process Reader Helper avoids rare abnormal termination

    GTM-6332

    C9J01-003085

    Other

    Code generation cleanup on Linux

    GTM-6598

    C9K04-003268

    Admin

    Limit the time MUPIP BACKUP and INTEG wait for kill-in-progress to clear

    GTM-6699

    D9K10-002792

    DB

    Opt-in facility for statistics sharing [!New Feature!]

    GTM-6793

    C9L04-003395

    Language

    Limit MERGE into an lvn to 31 subscripts

    GTM-6838

    C9L06-003425

    DB

    Asynchronous database IO [!New Feature!]

    GTM-7593

    -

    Admin

    More reliable journal flushing in edge cases under replication

    GTM-7729

    -

    Admin

    LOCKs have separate resource management by default, but you can select shared resource management [!New Feature!]

    GTM-7778

    -

    Other

    More consistent timestamps on AIX gtmsecshr messages

    GTM-7837

    -

    Admin

    MUPIP REPLICATE -CHANGELOG waits for up to 25 seconds to confirm a change log request

    GTM-7857

    -

    DB

    Reporting of empty-string subscripts that conflict with database settings

    GTM-7922

    -

    Admin

    MUPIP EXTRACT protects against concurrent updates to region spanning updates

    GTM-8254

    -

    Language

    USE command accepts [I|O]CHSET for Sequential Disks, SOCKETs and terminals [!New Feature!]

    GTM-8357

    -

    Language

    GT.M initializes the value of $ZSTEP from the environment variable $gtm_zstep if it is defined

    GTM-8359

    -

    Language

    More general support for indirect arguments to TSTART commands and an explicit error for TSTART in direct mode

    GTM-8362

    -

    Admin

    Allow updates during a MUPIP FREEZE

    GTM-8366

    -

    Language

    Clear $REFERENCE after an error in a global reference

    GTM-8373

    -

    Admin

    Accept rapid changes to replication logs destination files

    GTM-8385

    -

    Language

    Computations using literals largely performed at compile time [!New Feature!]

    GTM-8427

    -

    Language

    $ZCOLLATE() converts a GVN and $ZATRANSLATE() an expression to a key representation and back [!New Feature!]

    GTM-8430

    -

    Other

    Improvement in critical section acquisition for x86_64 Linux

    GTM-8447

    -

    Admin

    MUPIP DUMPFHEAD provides lighter weight and less problematic access to database state information [!New Feature!]

    GTM-8542

    -

    Admin

    MUPIP LOAD -FORMAT=Binary validates keys in the extract records

    GTM-8544

    -

    Other

    Timer interrupt reduction

    GTM-8553

    -

    DB

    Eliminate an interaction between poollimit and extended global references

    GTM-8559

    -

    Language

    $gtm_etrap and $gtm_trigger_etrap accept 8192 byte strings [!New Feature!]

    GTM-8561

    -

    Other

    Deal appropriately with M process data exceeding 2GiB

    GTM-8562

    -

    Other

    The configure install script creates routine directories even when reusing an existing directory

    GTM-8564

    -

    Admin

    Protect an interrupted MUPIP REORG -ENCRYPT from an intervening MUPIP REORG -TRUNCATE

    GTM-8567

    -

    Other

    configure script defaults locale to allow a UTF-8 installation to proceed

    GTM-8568

    -

    Language

    Fix three rare trigger update issues

    GTM-8569

    -

    Other

    Prevent rare duplicate messages when the number of processes in an instance exceeds 32ki

    GTM-8570

    -

    Other

    Eliminate superfluous literals from object modules

    GTM-8571

    -

    Other

    Fix regression in ^%GI for GO format containing any empty data values

    GTM-8572

    -

    Language

    Prevent instances of pre-evaluation in $SELECT()

    GTM-8573

    -

    Language

    Compiler optimization for IF <literal> and command postconditional literals [!New Feature!]

    GTM-8578

    -

    Other

    Correct handling of non-char arrays in %PEEKBYNAME()

    GTM-8579

    -

    Language

    Operator optimizations at compile time [!New Feature!]

    GTM-8582

    -

    Admin

    Appropriate Source Server startup with Sync I/O and 4KiB sector sizes on an XFS filesystem

    GTM-8583

    -

    Language

    Prevent inappropriate MAXNRSUBSCRIPTS errors from MERGE

    GTM-8584

    -

    Language

    Prevent GTMASSERT caused by a <NUL> character generating a NOCANONICNAME error message

    GTM-8590

    -

    Language

    Certain timed operations deferred during $ZCONVERT()

    GTM-8593

    -

    Language

    OPEN of an existing SOCKET device can modify ZFF & delimiters; also $KEY is always in UTF-8 [!New Feature!]

    GTM-8595

    -

    Language

    Fix to M mode handling of non-ASCII literals

    GTM-8597

    -

    DB

    Better protection against one type of random error

    GTM-8598

    -

    Other

    Certain operations deferred while processing character input

    GTM-8599

    -

    Admin

    Correct odd case for MUPIP JOURNAL -ROLLBACK -FORWARD

    GTM-8602

    -

    Other

    MUPIP JOURNAL accepts multiple EOF records

    GTM-8609

    -

    Admin

    Improved error messaging for errors that occur during the first access of a journal file

    GTM-8610

    -

    Admin

    The Receiver Server avoids rare situations that could cause it to exit

    GTM-8612

    -

    Admin

    MUPIP LOAD handles minimal headers and long lines gracefully

    GTM-8613

    -

    DB

    Protect against concurrent creation of global variable with differing collation characteristics

    GTM-8614

    -

    Admin

    REQROLLBACK message indicates required -ROLLBACK also requires -NOONLINE

    GTM-8615

    -

    Other

    Certain timed operations deferred during external calls

    GTM-8629

    -

    Admin

    MUPIP RESTORE treats truncated input as an error

    GTM-8637

    -

    Other

    Prevent GTMASSERT2 from very long running jobs performing TP transactions

    GTM-8639

    -

    Language

    ZSHOW "G" provides Block Transition to Dirty (BTD) statistic for BG databases [!New Feature!]

    GTM-8640

    -

    Language

    Accept <NUL> characters in literals use for indirection and XECUTE

    GTM-8641

    -

    DB

    $ORDER(,-1) of global variables that span database blocks returns correct result

    GTM-8642

    -

    Other

    Prevent rare inappropriate GTMASSERT2 from MUPIP STOP of a process while changing encryption keys

    GTM-8645

    -

    Other

    Improved (but imperfect) tracking of database reference count

    GTM-8654

    -

    Admin

    Revised permission handling when determining group membership [!New Feature!]

    GTM-8655

    -

    DB

    Improved database structural integrity protection against kill -9

    GTM-8656

    Admin

    Support for OpenSSL 1.1.0

    GTM-8657

    -

    Admin

    Replication from BC to SI handles multiple connections with no intervening updates

    GTM-8659

    -

    Other

    Better file cleanup in case of abnormal termination during file creation

    GTM-8660

    -

    Admin

    Improved System Profiling for x86_64 Linux editions

    GTM-8664

    -

    DB

    Defer idle epoch while holding journal pool critical section lock.

    GTM-8668

    -

    Admin

    Simplify GPG Agent interaction with the encryption reference implementation

    GTM-8672

    -

    Language

    Adjustments to improve the memory utilization for heap space (primarily local variable storage)

    GTM-8676

    -

    Other

    Fix to DSE FIND -KEY

    GTM-8679

    -

    Language

    Global name-level $ORDER() maintains $REFERENCE

    GTM-8686

    -

    Other

    ^%TI works as documented

    GTM-8687

    -

    DB

    GT.M properly handles loading successive global directories with increasing numbers of regions

    GTM-8689

    -

    Language

    Protect OPEN command against external actions

    Database

    • V63-001 GT.M defers the hardening (fsync) of a journaled database file (a potentially time consuming operation) to occur as much as possible outside the database critical section, particularly when it is time to write an EPOCH record in the journal file. Previously, this was done while holding the critical section which could affect database transaction throughput. (GTM-5206)

    • V63-001MUPIP INTEG, DSE INTEG and in some instances VIEW "GDSCERT" produce a NONUMSUBS error if they encounter a numeric subscript in a global variable tree that has been defined to only use string subscripts; previously, they did not report this issue. (GTM-6037)

    • V63-001 GT.M provides a fast and efficient mechanism for processes to share their database access statistics for other processes to monitor. In addition GT.M now supports implicit instantiation of a database file. Please refer to the Additional_Information section for the details and implications of this feature. (GTM-6699) [!New Feature!]

    • V63-001 Released as field test grade functionality in a production release, asynchronous IO is an option for database segments using the BG access method; previously GT.M performed only synchronous I/O through the file system cache. Also, when invoked from the shell, GDE returns a non-zero status in case it terminates with errors; previously it always returned a zero status, even if it encountered errors. Note: when invoked from GT.M, GDE does not return a status. MUPIP RUNDOWN appropriately manages the FTOK semaphore associated with a database to which it has read-only access; previously it inappropriately removed that semaphore if the database was quiescent but its attachment counter had ever exceeded 32Ki simultaneous processes. Please refer to the Additional Information section for details. (GTM-6838) [!New Feature!]

    • V63-001 When MUPIP INTEG, DSE INTEG -BLOCK, or VIEW "GDSCERT":1 processing encounter an empty-string ("null") subscript that does not match current file header settings for the null characteristic they issue a DBNULCOL or NULLSUBS error. If MUPIP LOAD-FORMAT=BINARY encounters empty-string subscripts in an extract it is loading on a database that does not permit such subscripts, it produces a NULLSUBS error. Previously, these functions did not report these errors (MUPIP LOAD did not load the offending data). Also, if MUPIP LOAD -FORMAT=BINARY encounters two keys that are the same except for their representations of empty string subscripts, it produces a warning message and discards the one whose representation does not match that of the database into which the data is being loaded. (GTM-7857)

    • V63-001 Extended references work correctly when poollimit is enabled. Previously, such a combination could produce GTMASSERT failures. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8553)

    • V63-001 GT.M protects itself against one type of random error in a control field used for buffer management. Previously, recovery required shutting the database down. The error observed most likely resulted from some sort of hardware malfunction. Note that FIS recommmends the use of ECC RAM in production systems. (GTM-8597)

    • V63-001 GT.M issues a ACTCOLLMISMTCH error in case multiple processes concurrently attempt to create the first global node of a global variable using differing collation characteristics (defined through the -GBLNAME section of their respective global directories). Previously, it was possible for processes to proceed to update with conflicting views of the global's collation, resulting in global nodes with misaligned collation sequences in the same global, creating an application level data integrity error. This issue was only observed in the GT.M development environment, and was never reported by a user.(GTM-8613)

    • V63-001 $ORDER(gvn,-1) and $ZPREVIOUS(gvn) work correctly in case of spanning nodes. Since GT.M V6.2-002, due to a regression introduced in GTM-7917, it could return the same value as the last subscript in the input key in case the global corresponding to gvn contained spanning nodes. For example if ^X(3) existed and was a spanning node, $ORDER(^X(4),-1) would return 4 instead of 3, potentially leading to infinite loops. If ^X(3) was not a spanning node, $ORDER() would return the correct value. The return value was unaffected by the existence or non-existence of a subtree of ^X(3). (GTM-8641)

    • V63-001 GT.M does better in maintaining database integrity in the face of a kill -9 of a process in the middle of a database commit. Previously, if a process trying to update a particular GDS block was killed in the middle of a commit, it was possible to lose prior updates to just that block within the same epoch, resulting in a database file with structural damage. Note that FIS continues to strongly recommend against kill -9 of processes that have opened a database file. (GTM-8655)

    • V63-001 GT.M defers performing an idle epoch if it concurrently holds the journal pool critical section lock. Previously, under rare conditions, performing the idle epoch in this situation could result in database deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8664)

    • GT.M marks journal files as current or not current, which allows it to deal more appropriately with an operational situation in which an operator renamed an older journal file as current. Previously, GT.M MUPIP ROLLBACK -FORWARD could not detect this operational issue and consequently failed to deliver a consistent state at completion. (GTM-8685)

    • V63-001 GT.M now properly handles loading multiple global directories with increasing numbers of regions. Previously, this could have resulted in memory corruption if a process first opened the first global directory with fewer regions AND both global directories had at least one global variable name that spanned multiple regions. This issue was never reported by users and was only seen in the GT.M development environment. (GTM-8687)

    • Operations on statistics database files (e.g. VIEW "STATSHARE", VIEW "NOSTATSHARE", direct access to ^%YGS global nodes) work correctly even in the case a process accesses the same statistics database file through more than one global directory. In GT.M V6.3-001, this could cause the process to terminate abnormally with a segmentation violation (SIG-11). GT.M correctly creates statistics database files (which are always created dynamically) even in case of heavy database contention amongst processes. In GT.M V6.3-001, if a process in a TP transaction (TSTART/TCOMMIT fence) was in its final retry (due to restarts from other concurrently running processes), it was rare but possible to encounter a deadlock. $ZPEEK issues a BADZPEEKARG error when its argument specifies a non-existent lower-case region name. In GT.M V6.3-001, this terminated the process with a segmentation violation (SIG-11). MERGE, ZWRITE, $DATA(), $ORDER(), and $QUERY() involving ^%YGS open any implicitly associated statistics database files when run outside of a TP transaction. In GT.M V6.3-001, they could ignore ^%YGS nodes corresponding to regions previously unopened or untracked by the process. Note that these operations within an explicit TP transaction do not implicitly open any not-yet-open statistics database until after the transaction commits. GT.M correctly handles a MUPIP SET -REPLICATION=ON for a region which was still replicating after journaling turned off (in the "was_on" state). In GT.M V6.3-001, due to a regression introduced by GTM-7593, an exiting process executing in a small window of instructions in database rundown logic could, in rare, cases terminate with a segmentation violation (SIG-11). MUPIP SET JOURNAL and MUPIP REPLICATE -INSTANCE_CREATE issue appropriate errors when their input attempts to create journal and/or replication-instance file names whose absolute path is more than 255 bytes long. Previously, it was possible for these commands to abnormally terminate with a "stack smashing detected" error due to GT.M-internal buffer overflows. All these issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8700)

    • Updates within explicit (TSTART/TCOMMIT) or implicit (spanning nodes or regions, or triggers) transactions requiring one or more additional blocks reliably write before images (if configured) to the journal file or to a MUPIP BACKUP -ONLINE. Missing before images could cause incorrect or damaged databases after a MUPIP JOURNAL -RECOVER or -ROLLBACK, or in a backup. In GT.M V6.3-001, due to a flaw in GTM-8637, in rare cases when choosing a previously freed block, GT.M failed to appropriately write a before image. This issue were only observed in the GT.M development environment, and was never reported by a user.(GTM-8702)

    Language

    • V63-001 MERGE into a local variable (lvn) target limits the number of target subscripts to the maximum number supported by GT.M (currently 31); previously, MERGE could produce variables with 32 subscripts which could cause subsequent problems. (GTM-6793)

    • V63-001 The USE command accepts [I|O]CHSET as valid deviceparameters. It is possible to change the character set of an open device. In addition to USE, the OPEN command also changes the character set of an already opened device including Sequential Disk, SOCKET and terminal devices. It is useful to deal with binary data intermixed with character data. Previously, there was no documented way to change the character set of an open device. (GTM-8254) [!New Feature!]

    • V63-001 GT.M takes the initial value of $ZSTEP from the environment variable gtm_zstep, with a default value of "B" (a BREAK command) if gtm_zstep is not defined; previously, changing the default value required a SET command. (GTM-8357)

    • V63-001 TSTART commands with indirect arguments work correctly in GT.M. Previously, they allowed only specification of a single local variable with no parentheses, SERIAL flag or transaction id parameter. Also, use of TSTART in direct mode is prohibited and generates a NODMTSTART error. Previously, TSTART/TCOMMIT sometimes worked when on the same direct mode command line but more often got strange errors and caused memory leaks at best. (GTM-8359)

    • V63-001 GT.M assigns an empty string to $REFERENCE when there is an error while constructing a subscripted global variable. Previously, GT.M assigned the last successful subscripted global variable to $REFERENCE. (GTM-8366)

    • V63-001 GT.M performs arithmetic operations involving only literals at compile time, with the exception of divide and integer divide (/ and \) by zero (0), which because of their use to intentionally produce an error is left to run time. Note that modulo (#) produces a compile time error. Previously, GT.M did all such calculations at run-time. (GTM-8385) [!New Feature!]

    • V63-001 $ZCOLLATE(glvn,intexpr[,{0|1}]) returns a transformed representation of a first argument glvn using the alternative transform specified by the second argument intexpr that, by default, or if the optional third argument is zero (0), represents a normalized form that can be used as an operand to the follows (]) or sorts-after operator ([[) such that, if both operands are in the normalized form, the result is independent of alternative collation. If the optional third argument is non-zero, $ZCOLLATE() returns a reverse transform of the first argument intended to restore the normalized form to the native M glvn representation. $ZCOLLATE() replaces the "YGVN2GDS" and "YGDS2GVN" arguments to $VIEW(), which are deprecated. $ZATRANSFORM(expr,intexpr[,{0|1}][,{0|1}]) returns a transformed representation of a first argument expr, treated as a subscripted or unsubscripted key, using the alternative transform specified by the second argument intexpr in a normalized form that can be used as an operand to the follows (]) or sorts-after (]]) operator such that, if both operands are in the normalized form, the result is independent of alternative collation. If the optional third argument is non-zero, $ZATRANSFORM() returns a reverse transform of the first argument intended to restore a normalized form to the native M expr representation. By default, or if the optional fourth argument is zero, $ZATRANSFORM()returns the transformation of expr using standard M collation of numbers before strings, causing numbers to sort like strings; if the optional third argument is non-zero, $ZATRANSFORM() treats all expressions as strings.(GTM-8427) [!New Feature!]

    • V63-001 $gtm_etrap and $gtm_trigger_etrap accept up to 8192 bytes and produce a LOGTOOLONG message in the syslog when ignoring a value longer than 8192. Previously, process initialization limited both environment variables to 4096 bytes and did not log any message for an over-length $gtm_trigger_etrap. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8559) [!New Feature!]

    • V63-001 $ZTRIGGER() operations that affect triggers executed in the same transaction work as documented. Previously, in rare situations, transactions that performed $ZTRIGGER() operations in some, but not all, retries and invoked a trigger affected by the $ZTRIGGER() operation in some, but not all, retries could result in a TRIGDEFBAD or SIG-11. Also, trigger load operations in which an error occurred only perform a validity check on trigger delete by name operations. Previously, if an error occurred during a trigger load, a subsequent trigger delete by name operation resulted in a TRIGDEFBAD if the name targeted a trigger installed as part of the current load operation. In addition, concurrent MUPIP REORG works appropriately with GT.M triggers. Previously, in rare situations, a concurrent MUPIP REORG could cause GT.M trigger operations to issue TRIGDEFBAD errors. These issues were only observed in the GT.M development environment, and were never reported by a user. (GTM-8568)

    • V63-001 $SELECT() does not pre-evaluate any expressions. A regression introduced in V6.2-002A related to GTM-8376 resulted in inappropriate pre-evaluation of arguments in some cases, especially when both FULL_BOOLEAN and gtm_side_effects modes were off. This caused inappropriate behavior such as errors in $SELECT() formulations intended to prevent execution of inappropriate indirection or $INCREMENT() acting on a global variable. (GTM-8572)

    • V63-001 When the argument of an IF command is a literal value or expression, the GT.M compiler generates code to set $TEST appropriately and ignores the rest of the line. When the argument of a command postconditional is a literal value or expression, the GT.M compiler evaluates the postconditional and either generates code for an unconditional command or omits generation for the command. Previously, the computation was performed at run time. Note that literal postconditionals evaluating to 0 result in smaller object modules than literal postconditionals evaluating to non-zero values. (GTM-8573) [!New Feature!]

    • V63-001 As part of compilation, GT.M optimizes unary operations, and binary operations, where both operands are literals; cases where the first operand is an empty string, divide and integer divide (/ or \) by zero (0) are exceptions. In addition, it treats $ZCHSET and $ZVERSION as compile time constants. Please observe the following cautions: ensure you compile with the same GT.M version, $gtm_chset, $gtm_local_collate, $gtm_patnumeric, $gtm_pattern_file and $gtm_pattern_table values (or lack thereof) as those used to run your application, and use variable operands, indirection or XECUTE for operands used with pattern match (?) or sorts-after (]]) if the application changes the run time values controlled by those environment variables. Note that the compiler detects a few errors at slightly different points which may change some messages, hopefully for the better. In addition, this change prevents a possible segmentation violation (SIG-11) in V6.3-000[A] when attempting to MUMPS -RUN of a routine with no current object module when the routine uses ZWRITE. (GTM-8579) [!New Feature!]

    • V63-001 MERGE permits its target to hold the maximum number of subscripts supported by GT.M (currently 31). Beginning with V6.1-000 the change associated with GTM-7867 could cause inappropriate MAXNRSUBSCRIPTS errors when the source and the target were both global variables, most likely when the source had many subscripts. The workaround was to MERGE the source into a local variable and then MERGE from there to the actual target. (GTM-8583)

    • V63-001 $QLENGTH(), $QSUBSCRIPT() and $ZCOLLATE() use ZWRITE format to report the namevalue in any NOCANONICNAME error. Previously, a <NUL> byte in the input resulted in a GTMASSERT. (GTM-8584)

    • V63-001 GT.M defers certain timed operations while performing a $ZCONVERT(); previously, the function could hang if interrupted by an timed operation that invoked non-reentrantsystem memory management services. This issue was only observed in the GT.M development environment, and was never reported by a user.(GTM-8590)

    • V63-001 Deviceparameters on the OPEN command for SOCKET device containing open sockets can modify the ZFF and delimiters of the current socket; previously, these could only be changed with a USE command. In addition, $KEY and $ZB for SOCKET devices appropriately return UTF-8 representations of the characters; previously, if the device character set was UTF-16[BE|LE], the terminator representations were inappropriately also encoded in UTF-16[BE|LE]. (GTM-8593) [!New Feature!]

    • V63-001 In M mode, $ASCII() of literal characters returns the correct value. In V6.3-000/-000A, this returned an incorrect value, typically -1 (it worked correctly for ASCII literal characters, for variable arguments, and in UTF-8 mode). Note that this is an edge case: instead of coding $ASCII() of a literal, one would normally just use the value, e.g., 65 instead of $ASCII("A"), and furthermore, the supported character set for literals in M programs is a subset of ASCII, whereas the issue affected literals corresponding to the non-ASCII characters $CHAR(128) through $CHAR(255). (GTM-8595)

    • V63-001 ZSHOW "G" and $VIEW("GVSTAT") report a count BTD, which for database regions that use the BG access method is the number of times a global buffer has transitioned from an clean (unmodified) state to a dirty (modified) state. For database regions that use the MM access method, BTD is zero. (GTM-8639) [!New Feature!]

    • V63-001 GT.M accepts NUL characters ($CHAR(0)) within literals used in indirection and XECUTE; previously, it generated errors for that character. (GTM-8640)

    • V63-001GT.M now reduces the active memory usage when a process uses a large amount of memory then subsequently uses a significantly reduced amount. Previously, active memory usage was distributed across the whole memory segment. In addition, $VIEW("SPSIZE") now returns three sizes (as comma separated values): the total amount of space allocated to the heap, amount of heap space in use, and amount of heap space reserved. The reserved space is used to reduce the active memory usage as mentioned above. GT.M now extends memory used for local variables more frequently when garbage collection does not reclaim a significant amount of space.(GTM-8672)

    • V63-001 Name-level $ORDER() on globals maintains $REFERENCE analogously to other $ORDER() invocations, that is: by reflecting the first argument unless a subsequent global reference in the second argument takes precedence; previously, it left $REFERENCE empty except when the second argument was a variable. This also applies to $ZPREVIOUS(), which is a deprecated way to do a $ORDER(,-1). (GTM-8679)

    • V63-001 GT.M protects OPEN commands against the possibility they don't complete due to an interrupt or device failure; previously, there was a very small window where external actions such as <CTRL-C>, MUPIP INTRPT, or a device disconnect could leave a device partially set up, which could cause a subsequent segmentation violation (SIG-11). This was only encountered in the GT.M development environment and was never reported by a user. (GTM-8689)

    • ZSHOW/ZWRITE work correctly even if they encounter a relatively rare heap management action. Previously, these commands could terminate with a segmentation violation (SIG-11) in these rare cases. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8705)

    System Administration

    • V63-001 MUPIP BACKUP and INTEG wait approximately one minute for any kill-in-progress to clear. Previously, the times exceeded the documented one minute time by three times for INTEG and an amount for BACKUP that was a function of the number of regions with kill-in-progress indicators; abandoned indicators showed this issue most strongly. These problems were never reported by users and were only seen in the GT.M development environment. (GTM-6598)

    • V63-001 GT.M flushes dirty journal and database buffers to disk in a timely manner in a replicated environment. Additionally, the Source Server recovers from an unflushed journal buffer situation by taking on the task of flushing, if needed, every eight (8) seconds while waiting for a journal record in the journal file. It logs a "REPL_INFO : Source server did flush of journal file" message to record such an event. Previously, it was possible in a rare case, involving journal file switches and process exits, for the buffers to stay unflushed causing the Source Server to issue a "REPL_WARN: Check for problems with journaling" alert every 50 seconds. The workaround for this situation was to start a new process that did an update or shut the source server down. (GTM-7593)

    • V63-001GDE ADD, CHANGE and TEMPLATE for REGION objects recognize the -[NO]LOCK_CRIT qualifier; MUPIP SET recognizes a -[NO]LCK_SHARES_DB_CRIT qualifier. Both control whether LOCK actions share the same resource and management as the database or use a separate resource and management. The GDE choice only affects database file creation with MUPIP CREATE. GDE SHOW -ALL and -REGION, and DSE DUMP -FILEHEADER each display the choice, which defaults to Sep(arate)/FALSE. Previously LOCK actions used the same resource and manager. While we expect this to have either no effect or a positive effect on performance depending on the application use patterns, it is different by default, so you should be aware of this change. (GTM-7729) [!New Feature!]

    • V63-001 MUPIP REPLICATE -CHANGELOG waits for up to twenty-five seconds for confirmation from Source and Receiver Server processes that the change succeeded (it may not for a variety of reasons). Previously, only MUPIP REPLICATE -RECEIVER -CHANGELOG waited; MUPIP REPLICATE -SOURCE -CHANGELOG did not. (GTM-7837)

    • V63-001 MUPIP EXTRACT appropriately handles the case where a concurrent process updates a spanning node that MUPIP EXTRACT is processing; previously, this situation could cause a segmentation violation (SIG-11). Note that running an EXTRACT without -FREEZE and with concurrent activity produces an inconsistent output (GTM-7922)

    • V63-001MUPIP FREEZE -ON -ONLINE freezes updates to the database file, but allows updates to memory and journal files to continue. As for normal freezes, the Online Freeze is removed by a MUPIP FREEZE -OFF. Online Freeze may only be used on regions with the BG access method.

      In the Online Freeze state, GT.M prevents casual database updates from occurring, including background flushing and timed epochs. However, certain conditions require updates to the database file, including full database buffers, journal file switches, and database file extensions. The -[NO]AUTORELEASE option may be used with the -ON option to select the behavior in these conditions, with -AUTORELEASE being the default. If a GT.M process autoreleases an Online Freeze, it sends an OFRZAUTOREL message to the operator log, all processes will be allowed to write to the database file, and a subsequent MUPIP FREEZE -OFF will warn that an Online Freeze had been removed. In this case any database copy or snapshot should be considered suspect and retried. If -NOAUTORELEASE is specified, memory updates will be suspended rather than release the freeze. If a process encounters this situation while holding a critical resource, it will send an OFRZCRITSTUCK message to the operator log and wait, which will prevent other operations on the region. When the Online Freeze is removed by a MUPIP FREEZE -OFF, the waiting process will send a OFRZCRITREL message to the operator log.

      Some commands which cannot run with an Online Freeze, e.g., MUPIP BACKUP and MUPIP SET -JOURNAL, will either autorelease or issue an OFRZACTIVE error, depending on the -[NO]AUTORELEASE option used to set the freeze. Other commands, e.g., MUPIP EXTEND, MUPIP REORG -TRUNCATE, and MUPIP INTEG -ONLINE, will either autorelease or hang until the Online Freeze is released.

      A MUPIP FREEZE -OFF must always follow a MUPIP FREEZE -ON -ONLINE, even in the case of an autorelease, to ensure that normal operations are resumed. In the case of an autorelease, the MUPIP FREEZE -OFF command will report a OFRZNOTHELD warning.

      To maximize the time that updates to memory may continue, MUPIP FREEZE -ON -ONLINE flushes all dirty buffers to disk and performs a journal file switch, but it does not perform a database extension. If a database file is nearly full, the user should consider doing a database file extension before the Online Freeze. When the previous FREEZE operation was -ONLINE, a MUPIP FREEZE -OFF flushes any dirty buffers to disk and performs a journal file switch. These operations are performed in such a way as to minimize impact to processes doing memory updates, but they do involve performing epochs, so there may be some delay to other processes.(GTM-8362)

    • V63-001 MUPIP replication servers accept changes to their log file destinations immediately after the last change; previously, they occasionally required a wait between changes. (GTM-8373)

    • V63-001 MUPIP DUMPFHEAD [-FILE <file-name>][-REGION <region-list>] provides a way to get substantially the same information as DSE DUMP -FILEHEADER, but in the same format as provided by %PEEKBYNAME, and without connecting to database files. It is both lighter weight than DSE and avoids the need to use DSE, for which operator error can have serious consequences. The formatting is more regular than that of DSE. As MUPIP DUMPFHEAD does not open shared memory, values reported for dynamic fields that are in shared memory may be stale. Because MUPIP DUMPFHEAD is implemented in MUMPS, application code can call getfields^%DUMPFHEAD(varname,dbfilename), where varname is a local variable name passed by reference, and dbfilename is the name of a database file, to generate the records dumped by MUPIP. Note that this facility supersedes ^%DSEWRAP, which is deprecated, is not updated or tested, and eventually will be withdrawn. (GTM-8447) [!New Feature!]

    • V63-001 MUPIP LOAD -FORMAT=BINARY validates the keys in the extract records and reports any errors it detects before skipping the bad record and any following records in the block. Previously, LOAD of a binary extract did not validate incoming keys. (GTM-8542)

    • V63-001 MUPIP REORG -ENCRYPT works correctly when reissued after a prior invocation of the same command was interrupted. Previously, if a MUPIP REORG -TRUNCATE was run in between and did truncate the database, it was possible for the reissued MUPIP REORG -ENCRYPT to incorrectly succeed even though it did not finish the (re)encryption. This was particularly evident if one ran a MUPIP SET -ENCRYPTIONCOMPLETE command on the same database which correctly indicated the encryption as incomplete. This issue was only observed in the GT.M development environment, and was never reported by a user. A workaround for this was to run a MUPIP EXTEND on the database and reissue the MUPIP REORG -ENCRYPT. (GTM-8564)

    • V63-001 Enabling sync_io for journaling works correctly on XFS filesystems configured with 4KiB sector sizes. Previously, the Source Server could experience a REPLFILIOERR error with the message "Error in reading jfh in update_eof_addr" when reading from journal files. (GTM-8582)

    • V63-001 MUPIP JOURNAL -ROLLBACK -FORWARD correctly rolls the database forward in the case one region has a journal file with very limited update activity (less duration than the epoch interval of that region). Previously, it was possible, in the unlikely case of a crash (where the journal files were not cleanly shutdown) where a region had only a single epoch matching the safe restore time determined across all regions, for ROLLBACK to inappropriately set the database file header as if it had restored updates beyond those it actually restored, which could cause a subsequent replication restart to miss updates. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8599)

    • V63-001 The error messages for JNLTRANSLSS and JNLTRANSGTR now include the transaction numbers in the database file header and journal file header. The accompanying JNLOPNERR prints the name of the database and journal files. Previously, when issued alongside a JNLSENDOPER message, JNLOPNERR missed information about the database file, and there were no transaction numbers for JNLTRANSLSS or JNLTRANSGTR. The error JNLREADEOF omits the journal file name as the accompanying JNLEXTEND message prints this information.[/p][p]The error messages JNLBADRECFMT, JNLVSIZE, and CRYPTJNLMISMATCH include context information when a process fails to open a journal file for thefirst time. Previously, these error messages did not include some or all of the context information. (GTM-8609)

    • V63-001 The Receiver Server handles unusual protocol messages appropriately. Previously, in extremely rare circumstance, the Receiver Server could mishandle such a message and terminate with a segmentation violation or REPLTRANS2BIG error preceded by numerous "Received UNKNOWN message" messages. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8610)

    • V63-001 MUPIP LOAD does not terminate abnormally with a segmentation fault (SIG-11) when delivering the MAXSTRLEN error nor does MUPIP LOAD treat a 12 byte header as a MAXSTRLEN error. Previously, a 12 byte header line in a GO or ZWRITE extract could cause GT.M to terminate abnormally with a segmentation fault (SIG-11). The workaround for the short header was to edit it in order to pad the length. (GTM-8612)

    • V63-001 The REQROLLBACK message indicates that required -ROLLBACK also requires the -NOONLINE qualifier.(GTM-8614)

    • V63-001 MUPIP RESTORE issues an IOEOF error and exits with a non-zero status when supplied with a truncated backup file. Previously, it used to prompt for the next volume to be mounted and later issue a SYSTEM-E-UNKNOWN error and incorrectly exit with a zero status indicating normal exit. Additionally, it cleans up database semaphore ipcs in case of errors; previously left two semaphores per database in case of errors.(GTM-8629)

    • V63-001 GT.M considers available process groups when determining permissions based on group membership for IPCs and files, like journals and snapshot files. Previously, when GT.M failed to determine group membership, GT.M inappropriately removed owner access to the IPCs that it created resulting either a PERMGENFAIL error or DBFILERR error followed by the supplemental text "Error with database control semctl SETVAL". (GTM-8654) [!New Feature!]

    • V63-001 The GT.M reference encryption plugin is compatible with OpenSSL 1.1.0. Previously, the plugin would not compile with OpenSSL 1.1.0. (GTM-8656)

    • V63-001 GT.M replication appropriately handles the case where a receiving Supplementary Instance (P) connects to a non-supplementary Originating Instance (A) for the first time and then reconnects with no intervening updates. Previously, if the A->P connection occurred twice with no intervening update, replication from P to another receiving Supplementary Instance (Q) failed with a STRMSEQMISMTCH error. (GTM-8657)

    • V63-001 GT.M makes more information available to system profiling tools such as perf. [x86_64 Linux] (GTM-8660)

    • V63-001 The GT.M reference encryption plugin Makefile copies the pinentry.m routine into $gtm_dist/plugin/gtmcrypt and the GT.M reference encryption plugin pinentry program includes $gtm_dist/plugin/r in the gtmroutines search path. Previously, if the encryption plug-in source archive was not extracted in $gtm_dist/plugin/gtmcrypt, the custom pinentry program failed to load the pinentry routine and the user would be prompted via the system default pinentry program.The GT.M Encryption plugin properly compiles when GT.M is installed without Unicode support. Previously, this would result in the Makefile exiting with an error. The GT.M encryption plugin includes support for loopback pinentry mode (available starting with GnuPG 2.1.12) which simplifies unattended passphrase handling.(GTM-8668)

    Other

    • V63-001 The GT.M compiler accepts input with <CR><LF> line termination (common on some non-POSIX Operating Systems); previously, it did not. Our thanks to the membership of the May 2016 "Hacking GT.M" workshop for this change. (GTM-4283) [!New Feature!]

    • V63-001 Update Process Reader Helpers operate correctly. Previously, under rare conditions the Reader Helper would encounter a segmentation violation (SIG-11). This was only encountered in the GT.M development environment, and was never reported by a user. (GTM-6085)

    • V63-001 Code using literals on Linux on x86_64 is faster, and the generated object file is smaller than previously. Compilation is also faster, which should, in turn, speed up operations using indirection and XECUTE. As with any performance enhancement, actual benefit will vary, depending on the extent to which application code uses constructs that benefit from this change. [x86_64 Linux] (GTM-6332)

    • V63-001 The gtmsecshr wrapper on AIX uses the standard system timezone taken from /etc/environment for the timestamps of any syslog entries it generates. It also passes this timezone on to gtmsecshr to use for its entries as well. Previously, syslog timestamps from the AIX gtmsecshr wrapper could be either in the timezone of the process that started gtmsecshr or UTC, depending on whether environment variables had been cleared at the time of the error or not. [AIX] (GTM-7778)

    • V63-001 Critical section acquitions are slightly more efficient. [x86_64 Linux] (GTM-8430)

    • V63-001 GT.M manages time-related tasks in a more lightweight fashion. On heavily loaded systems with large numbers of processes, this should reduce the number of interrupts and context switches that the operating system needs to process. In addition, GT.M processes time-related tasks in a timely fashion. Previously, in rare conditions, timed operations (e.g., HANG) could be delayed up to eight seconds. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8544)

    • V63-001 A GT.M process functions correctly when its M data heap exceeds 2GiB. Previously, such a process could experience damage to internal data structures, leading to incorrect process behavior including process termination with segmentation violations (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8561)

    • V63-001 The GT.M configure installation script always creates the plug-in routine source and object file directories. Previously, when installing over an existing directory the installation script did not create the plug-in routine source and object file directories. (GTM-8562)

    • V63-001 When directed to install GT.M with UTF-8 support, the configure script defaults to the C.UTF-8 locale when systems have none defined. Previously, the configure script terminated prematurely on such a condition. This was only seen by users building GT.M from source in a restricted build environment. (GTM-8567)

    • V63-001 When starting up, the replication Receiver Server only issues a NOMORESEMCNT message to the syslog if it is the first process to determine that more than 32Ki GT.M processes have run in that instance. Previously, in very rare cases, it could inappropriately log a duplicate message. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8569)

    • V63-001 The GT.M compiler reduces the size of object modules by not placing literals in an object module once the compilation eliminates a need for them. Previously, it sometimes left obsolete literals in the object files; in V6.3-000[A], GTM-7762 made this a more significant issue. (GTM-8570)

    • V63-001 ^%GI appropriately handles empty string data values in GO format input. In V6.3-000 and V6.3-000A, ^%GI ignored such input, leading to incorrect loads. The workaround was to use ZWR format or MUPIP LOAD. (GTM-8571)

    • V63-001 ^%PEEKBYNAME() handles cases where the type of data it is to access is an array of known types by returning a comma delimited list of the array elements; for example, $$^%PEEKBYNAME("sgmnt_data.tp_cdb_sc_blkmod",base) returns a string in the form "0,0,0,0,0,0,0,0" because the arguments identify an array of 8 integers (type int). Previously, this kind of invocation produced a BADZPEEKFMT error. (GTM-8578)

    • V63-001 GT.M briefly defers certain operations while processing character input; previously, the non-reentrant system memory management services used in character-based input could hang a process if their timed operations also invoked memory management services. (GTM-8598)

    • V63-001 MUPIP JOURNAL accepts multiple EOF records in the same journal file. Multiple EOF records only occur when the last process to halt out of a journaled database terminates abnormally just before cleanly shutting down the journal file. Note that FIS strongly recommends against using kill -9 on any GT.M process performing database updates. Previously, MUPIP JOURNAL produced a GTM-E-JNLUNXPCTERR error when it encountered multiple EOF records in a journal file. (GTM-8602)

    • V63-001 GT.M prevents certain timed operations during external calls. Previously, in an environment using encrypted databases,an external call could cause the process to hang due to an invocation of non-reentrant memory management system services also invoked by the encryption plug-in. (GTM-8615)

    • The gtm_coredump_filter environment variable specifies the mappings of the process address space for a GT.M process, with the bits having the same meaning as those specified for /proc/<pid>/coredump_filter in "man 5 core". If unspecified, GT.M uses a value of 0x73; a value of -1 prevents GT.M from modifying the coredump_filter value. A running process can change its coredump_filter by writing to the file /proc/<pid /coredump_filter, and can query the current value by reading that file. [Linux x86_64] (GTM-8632)

    • V63-001 Processes handle a large volume of TP updates appropriately; previously, a long-running process, such as an Update Process, adding new global nodes could eventually inappropriately terminate with a GTMASSERT2. (GTM-8637)

    • V63-001 GT.M appropriately handles the case of a process receiving a MUPIP STOP while another process has recently been performing a MUPIP REORG -ENCRYPT to change the encryption keys. In V6.3-000[A] this combination could rarely cause the stopped process to terminate with a GTMASSERT2 error. This caused no problems for the database. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8642)

    • V63-001 GT.M more accurately maintains the count of the number of processes attached to a database file $$^%PEEKBYNAME("node_local.ref_cnt",<region>) or "Reference count" in DSE DUMP -FILE output. Note that GT.M does not rely on this field, which exists to supply operational information to the user, but which may be inaccurate if processes are subject to kill - 9 - something that FIS recommends against and that GT.M does not guard against. Previously, in case the database has the quick-rundown mode enabled (MUPIP SET -QDBRUNDOWN), this counter could become inaccurate even without interference from kill -9. (GTM-8645)

    • V63-001 When GT.M exits with a fatal error, such as GTM-F-MEMORY, it cleans up any empty file it was in the process of creating at the time of the failure. This applies to GT.M OPEN, DSE OPEN and a number of MUPIP functions which create files. Previously, this unusual situation left an empty file and in some cases the process terminated with a segmentation fault (SIG-11). (GTM-8659)

    • V63-001 DSE FIND -KEY reports the correct path leading to the input key. For versions V6.0-000 to V6.3-000A, due to a regression introduced by GTM-6341, it sometimes reported an incorrect Global tree path if the input key is not found in the database file. (GTM-8676)

    • V63-001 ^%TI works as documented; previously, it rejected some documented forms. (GTM-8686)

    More Information

    Additional information for GTM-6838 - Asynchronous database IO

    Released as field test grade functionality in a production release, asynchronous IO is an option for database segments using the BG access method; previously GT.M performed only synchronous I/O through the file system cache.

    • $$^%PEEKBYNAME("sgmnt_data.asyncio",<region-name>) - returns TRUE (1) if the region has asynchronous I/O enabled and FALSE (0) if it does not.
    • $$^%PEEKBYNAME("node_local.wcs_wip_lvl",<region-name>) - returns the number of blocks for which GT.M has issued writes that it has not yet recognized as complete.

    DSE DUMP -FILEHEADER reports the above information for a region as follows:

    • Async IO - whether AsyncIO is ON or OFF for the database
    • WIP queue cache blocks - the number of blocks for which GT.M has issued writes that it has not yet recognized as complete

    GDE ADD, CHANGE and TEMPLATE commands accept the following qualifier for SEGMENT objects with an access method of BG:

    • -[NO]ASYNCIO specifies whether to use asynchronous I/O for a database file; the default is NOASYNCIO.

    MUPIP SET recognizes the -[NO]ASYNCIO qualifier. As there are two MUPIP SET qualifiers beginning with "A", MUPIP no longer recognizes "-A" to specify "-ACCESS_METHOD" - please use the recommended minimum of four characters (-ACCE). Also, when a MUPIP SET command changes the database access method, it reports the change; previously it made the change silently.

    Database files have an empty database block logically after the last usable database block; previously this location had an empty 512 byte block. Because of this change, downgrading a database using V6.3-001 or later for use by a version prior to V6.3-001 requires a MUPIP DOWNGRADE -VERSION=V63000A. This syntax uses V63000A to specify DOWNGRADE change the terminating block from having the current size of a database block to using a 512-byte size used by all releases up to V6.3-000A, and should be used regardless of which release older than V6.3-001 you plan to use after the DOWNGRADE.

    For Linux x86_64, the gtm_aio_nr_events environment variable controls the number of structures a process has per global directory to manage asynchronous writes, and therefore determines the number of concurrent writes a process can manage across all regions within a global directory. If not specified, the value controlled by gtm_aio_nr_events defaults to 128. If a process encounters a situation where it needs to perform an asynchronous write, but has no available slots with which to manage an additional one, it either falls back to synchronous writing if the write is blocking other actions, and otherwise defers the write until a slot becomes available as other writes complete. Linux allocates the structures on a system-wide basis with the setting of /proc/sys/fs/aio-max-nr. Therefore you should configure this parameter to account for the needs (as determined by gtm_aio_nr_events or the default) of all processes using asynchronous I/O. When processes use multiple global directories with asynchronous I/O, their need for the system resources increases accordingly. For example, if an environment runs 10,000 processes each of which open two global directories and /proc/sys/fs/aio-max-nr is set to a value of 200,000 then gtm_aio_nr_events needs to be set to a value <= 200,000 / (10,000 * 2) = 10. Conversely if gtm_aio_nr_events is set to a value of 20, then aio-max-nr needs to be bumped up to (10,000 * 2 * 20) = 400,000. GT.M captures the number of errors encountered when attempting to write database blocks for a region, and, barring problems with the storage subsystem, hitting an asynchronous write limit would constitute primary (probably only) contribution to that value, which you can access with the following:

    • $$^%PEEKBYNAME("sgmnt_data.wcs_wterror_invoked_cntr",<region>)

    The performance characteristics of asynchronous IO are likely to be quite different from the traditional sequential IO. Although asynchronous IO in theory should be more efficient than synchronous IO by eliminating the need for the UNIX file buffer cache and eliminating certain filesystem locks, in practice asynchronous IO is likely to emerge from the starting gate under-performing synchronous IO because of the years that synchronous IO has been the common IO model operating systems and filesystems have had used by applications. So, you should anticipate extensive benchmarking and tuning for your application to achieve the best performance it can with asynchronous IO. Some notes and observations that we have to share:

    • As asynchronous IO dispenses with the UNIX file buffer cache, GT.M global buffers are the sole caching mechanism. To make asynchronous IO perform well, you will likely need to increase the number of global buffers considerably. With GT.M's limit of 2GiB per shared memory segment, a database segment with 4KiB blocks has a limit of almost two million global buffers.
    • A large number of global buffers potentially implies a large number of dirty global buffers to be flushed at an epoch. You should investigate the impact on application response time of GT.M epoch tapering vs. turning off epoch tapering and using a separate stand-alone process that executes a line of code such as: for set x="" for set x=$view("gvnext",x) quit:""=x view "dbflush":x,"dbsync":x,"epoch":x hang n where n is a number that causes each region to be flushed at an appropriate interval. If you choose this option, remember to turn off epoch tapering, and to set the epoch interval in the file header to be large enough to prevent application processes from performing epochs, and consider scripted timely switching of journal files by other than application processes (switching journal files involves an epoch).
    • diff --git a/articles/GTM_V6.3-003_Release_Notes.html b/articles/GTM_V6.3-003_Release_Notes.html index 48c13e5..8be488d 100644 --- a/articles/GTM_V6.3-003_Release_Notes.html +++ b/articles/GTM_V6.3-003_Release_Notes.html @@ -263,7 +263,7 @@ Fidelity National Information Services, Inc.
      to download the CONVDBKEYS.m program and follow instructions in the comments near the top of the program file. You can also download CONVDBKEYS.m from http://tinco.pair.com/bhaskar/gtm/doc/articles/downloadables/CONVDBKEYS.m. If you are using $gtm_dbkeys for database encryption, please convert master key files to libconfig format immediately after upgrading to V6.2-000 or later. Also, modify your environment scripts to include the use of gtmcrypt_config environment variable.

    Recompile

    • Recompile all M and C source files.

    Rebuild Shared Libraries or Images

    • Rebuild all Shared Libraries after recompiling all M and C source files.

    • If your application is not using object code shared using GT.M's auto-relink functionality, please consider using it.

    Compiling the Reference Implementation Plugin

    If you plan to use database encryption and TLS replication, you must compile the reference implementation plugin to match the shared library dependencies unique to your platform. The instructions for compiling the Reference Implementation plugin are as follows:

    1. Install the development headers and libraries for libgcrypt, libgpgme, libconfig, and libssl. On Linux, the package names of development libraries usually have a suffix such as -dev or -devel and are available through the package manager. For example, on Ubuntu_x86_64 a command like the following installs the required development libraries:

      sudo apt-get install libgcrypt11-dev libgpgme11-dev libconfig-dev libssl-dev

      Note that the package names may vary by distribution / version.

    2. Unpack $gtm_dist/plugin/gtmcrypt/source.tar to a temporary directory. 

      mkdir /tmp/plugin-build
 cd /tmp/plugin-build
 cp $gtm_dist/plugin/gtmcrypt/source.tar . 
-tar -xvf source.tar

    3. Follow the instructions in the README.

      • Open Makefile with your editor; review and edit the common header (IFLAGS) and library paths (LIBFLAGS) in the Makefile to reflect those on your system.

      • Define the gtm_dist environment variable to point to the absolute path for the directory where you have GT.M installed

      • Copy and paste the commands from the README to compile and install the encryption plugin with the permissions defined at install time

        [Caution]Caution

        There are separate steps to compile the encryption plugin for GT.M versions V5.3-004 through V6.3-000 when OpenSSL 1.1 is installed and OpenSSL 1.0.x libraries arestill available.

        • Download the most recent OpenSSL 1.0.x version

        • Compile and install (default installs to /usr/local/ssl)

          ./config && make install

        • Adjust the configuration : Move the newly installed libraries out of the way

          mv /usr/local/ssl/lib /usr/local/ssl/lib.donotuse

        • Adjust the configuration : Create another /usr/local/ssl/lib and symlink the existing 1.0.x library into it as the default. This ensures that the encryption plugin is compiled using the compatible OpenSSL 1.0.x library. Adjust the path below as necessary.

          mkdir /usr/local/ssl/lib && ln -s /path/to/existing/libssl.so.1.0.x /usr/local/ssl/libssl.so

        • Recompile the encryption plugin following existing directions above

        • Remove /usr/local/ssl to avoid future complications

    Upgrading to GT.M V6.3-003A

    The GT.M database consists of four types of components- database files, journal files, global directories, and replication instance files. The format of some database components differs for 32-bit and 64-bit GT.M releases for the x86 GNU/Linux platform.

    GT.M upgrade procedure for V6.3-003A consists of 5 stages:

    Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V6.3-003A depends on your GT.M upgrade history and your current version.

    Stage 1: Global Directory Upgrade

    FIS strongly recommends you back up your Global Directory file before upgrading. There is no one-step method for downgrading a Global Directory file to an older format.

    To upgrade from any previous version of GT.M:

    • Open your Global Directory with the GDE utility program of GT.M V6.3-003A.

    • Execute the EXIT command. This command automatically upgrades the Global Directory.

    To switch between 32- and 64-bit global directories on the x86 GNU/Linux platform:

    1. Open your Global Directory with the GDE utility program on the 32-bit platform.

    2. On GT.M versions that support SHOW -COMMAND, execute SHOW -COMMAND -FILE=file-name. This command stores the current Global Directory settings in the specified file.

    3. On GT.M versions that do not support GDE SHOW -COMMAND, execute the SHOW -ALL command. Use the information from the output to create an appropriate command file or use it as a guide to manually enter commands in GDE.

    4. Open GDE on the 64-bit platform. If you have a command file from 2. or 3., execute @file-name and then run the EXIT command. These commands automatically create the Global Directory. Otherwise use the GDE output from the old Global Directory and apply the settings in the new environment.

    An analogous procedure applies in the reverse direction.

    If you inadvertently open a Global Directory of an old 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 to downgrade to an old GT.M release:

    • Open the global directory with the GDE utility program of V6.3-003A.

    • Execute the SHOW -COMMAND -FILE=file-name command. This command stores the current Global Directory settings in the file-name command file. If the old version is significantly out of date, edit the command file to remove the commands that do not apply to the old format. Alternatively, you can use the output from SHOW -ALL or SHOW -COMMAND as a guide to manually enter equivalent GDE commands for the old version.

    Stage 2: Database Files Upgrade

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

    A V6 database file is a superset of a V5 database file and has potentially longer keys and records. Therefore, upgrading a database file requires no explicit procedure. After upgrading the Global Directory, opening a V5 database with a V6 process automatically upgrades fields in the database fileheader.

    A database created with V6 supports up to 992Mi blocks and is not backward compatible. V6 databases that take advantage of V6 limits on key size and records size cannot be downgraded. Use MUPIP DOWNGRADE -VERSION=V5 to downgrade a V6 database back to V5 format provided it meets the database downgrade requirements. For more information on downgrading a database, refer to Downgrading to V5 or V4.

    [Important] Important

    A V5 database that has been automatically upgraded to V6 can perform all GT.M V6.3-003A operations. However, that database can only grow to the maximum size of the version in which it was originally created. A database created on V5.0-000 through V5.3-003 has maximum size of 128Mi blocks. A database created on V5.4-000 through V5.5-000 has a maximum size of 224Mi blocks. A database file created with V6.0-000 (or above) can grow up to a maximum of 992Mi blocks. This means that, for example, the maximum size of a V6 database file having 8KiB block size is 7936GiB (8KiB*992Mi).

    [Important] Important

    In order to perform a database downgrade you must perform a MUPIP INTEG -NOONLINE. If the duration of the MUPIP INTEG exceeds the time allotted for an upgrade you should rely on a rolling upgrade scheme using replication.

    If your database has any previously used but free blocks from an earlier upgrade cycle (V4 to V5), you may need to execute the MUPIP REORG -UPGRADE command. If you have already executed the MUPIP REORG -UPGRADE command in a version prior to V5.3-003 and if subsequent versions cannot determine whether MUPIP REORG -UPGRADE performed all required actions, it sends warnings to the syslog requesting another run of MUPIP REORG -UPGRADE. In that case, perform any one of the following steps:

    • Execute the MUPIP REORG -UPGRADE command again, or

    • Execute the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command to stop the warnings.

    [Caution] Caution

    Do not run the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command unless you are absolutely sure of having previously run a MUPIP REORG -UPGRADE from V5.3-003 or later. An inappropriate DSE CHANGE -FILEHEADE -FULLY_UPGRADED=1 may lead to database integrity issues.

    You do not need to run MUPIP REORG -UPGRADE on:

    • A database that was created by a V5 MUPIP CREATE

    • A database that has been completely processed by a MUPIP REORG -UPGRADE from V5.3-003 or later.

    For additional upgrade considerations, refer to Database Compatibility Notes.

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

    You need to upgrade your database files only when there is a block format upgrade from V4 to V5. However, some versions, for example, database files 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.

    • 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.

    • Run the MUPIP REORG -UPGRADE command. This command upgrades all V4 blocks to V5 format.

    [Note] Note

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

    Database Compatibility Notes

    • Changes to the database file header may occur in any release. GT.M automatically upgrades database file headers as needed. Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.

    • Databases created with V5.3-004 through V5.5-000 can grow to a maximum size of 224Mi (234,881,024) blocks. This means, for example, that with an 8KiB block size, the maximum database file size is 1,792GiB; this is effectively the size of a single global variable that has a region to itself and does not itself span regions; a database consists of any number of global variables. A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128Mi to 224Mi blocks.

    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128Mi (134, 217,728) blocks. GT.M versions V5.0-000 through V5.3-003 can access databases created with V5.3-004 and later as long as they remain within a 128Mi block limit.

    • Database created with V6.0-000 or above have a maximum size of 1,040,187,392(992Mi) blocks.

    • For information on downgrading a database upgraded from V6 to V5, refer to: Downgrading to V5 or V4.

    Stage 3: Replication Instance File Upgrade

    V6.3-003A does not require new replication instance files if you are upgrading from V5.5-000. However, V6.3-003A requires new replication instance files if you are upgrading from any version prior to V5.5-000. Instructions for creating new replication instance files are in the Database Replication chapter of the GT.M Administration and Operations Guide. Shut down all Receiver Servers on other instances that are to receive updates from this instance, shut down this instance Source Server(s), recreate the instance file, restart the Source Server(s) and then restart any Receiver Server for this instance with the -UPDATERESYNC qualifier.

    [Note] 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.

    [Important] Important

    You must always follow the steps described in the Database Replication chapter of the GT.M Administration and Operations Guide when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

    Stage 4: Journal Files Upgrade

    On every GT.M upgrade:

    • Create a fresh backup of your database.

    • Generate new journal files (without back-links).

    [Important] Important

    This is necessary because MUPIP JOURNAL cannot use journal files from a release other than its own for RECOVER, ROLLBACK, or EXTRACT.

    Stage 5: Trigger Definitions Upgrade

    If you are upgrading from V5.4-002A/V5.4-002B/V5.5-000 to V6.3-003A and you have database triggers defined in V6.2-000 or earlier, you need to ensure that your trigger definitions are wholesome in the older version and then run MUPIP TRIGGER -UPGRADE. If you have doubts about the wholesomeness of the trigger definitions in the old version use the instructions below to capture the definitions delete them in the old version (-*), run MUPIP TRIGGER -UPGRADE in V6.3-003A and then reload them as described below.

    You need to extract and reload your trigger definitions only if you are upgrading from V5.4-000/V5.4-000A/V5.4-001 to V6.3-003A or if you find your prior version trigger definitions have problems. For versions V5.4-000/V5.4-000A/V5.4-001 this is necessary because multi-line XECUTEs for triggers require a different internal storage format for triggers which makes triggers created in V5.4-000/V5.4-000A/V5.4-001 incompatible with V5.4-002/V5.4-002A/V5.4-002B/V5.5-000/V6.0-000/V6.0-001/V6.3-003A.

    To extract and reapply the trigger definitions on V6.3-003A using MUPIP TRIGGER:

    1. Using the old version, execute a command like mupip trigger -select="*" trigger_defs.trg. Now, the output file trigger_defs.trg contains all trigger definitions.

    2. Place -* at the beginning of the trigger_defs.trg file to remove the old trigger definitions.

    3. Using V6.3-003A, run mupip trigger -triggerfile=trigger_defs.trg to reload your trigger definitions.

    To extract and reload trigger definitions on a V6.3-003A replicating instance using $ZTRIGGER():

    1. Shut down the instance using the old version of GT.M.

    2. Execute a command like mumps -run %XCMD 'i $ztrigger("select")' > trigger_defs.trg . Now, the output file trigger_defs.trg contains all trigger definitions.

    3. Turn off replication on all regions.

    4. Run mumps -run %XCMD 'i $ztrigger("item","-*") to remove the old trigger definitions.

    5. Perform the upgrade procedure applicable for V6.3-003A.

    6. Run mumps -run %XCMD 'if $ztrigger("file","trigger_defs.trg")' to reapply your trigger definitions.

    7. Turn replication on.

    8. Connect to the originating instance.

    [Note] Note

    Reloading triggers renumbers automatically generated trigger names.

    Downgrading to V5 or V4

    You can downgrade a GT.M V6 database to V5 or V4 format using MUPIP DOWNGRADE.

    Starting with V6.0-000, MUPIP DOWNGRADE supports the -VERSION qualifier with the following format: 

    MUPIP DOWNGRADE -VERSION=[V5|V4]

    -VERSION specifies the desired version for the database header.

    To qualify for a downgrade from V6 to V5, your database must meet the following requirements:

    1. The database was created with a major version no greater than the target version.

    2. The database does not contain any records that exceed the block size (spanning nodes).

    3. The sizes of all the keys in database are less than 256 bytes.

    4. There are no keys present in database with size greater than the Maximum-Key-Size specification in the database header, that is, Maximum-Key-Size is assured.

    5. The maximum Record size is small enough to accommodate key, overhead, and value within a block.

    To verify that your database meets all of the above requirements, execute MUPIP INTEG -NOONLINE. Note that the integrity check requires the use of -NOONLINE to ensure no concurrent updates invalidate the above requirements. Once assured that your database meets all the above requirements, MUPIP DOWNGRADE -VERSION=V5 resets the database header to V5 elements which makes it compatible with V5 versions.

    To qualify for a downgrade from V6 to V4, your database must meet the same downgrade requirements that are there for downgrading from V6 to V5.

    If your database meets the downgrade requirements, perform the following steps to downgrade to V4:

    1. In a GT.M V6.3-003A environment:

      1. Execute MUPIP SET -VERSION=v4 so that GT.M writes updates blocks in V4 format.

      2. Execute MUPIP REORG -DOWNGRADE to convert all blocks from V6 format to V4 format.

    2. Bring down all V6 GT.M processes and execute MUPIP RUNDOWN -FILE on each database file to ensure that there are no processes accessing the database files.

    3. Execute MUPIP DOWNGRADE -VERSION=V4 to change the database file header from V6 to V4.

    4. Restore or recreate all the V4 global directory files.

    5. Your database is now successfully downgraded to V4.

    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(R) (ISO/IEC-10646) character strings. On a system that does not have ICU 3.6 or later installed, GT.M only supports M mode.

    On a system that has ICU installed, GT.M optionally 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 it finds both a source and an object file, and the object predates the source file and was generated with the same setting of $gtm_chset/$ZCHset. A GT.M process generates 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 UTF-8 mode in the utf8 subdirectory, and one compiled without support for UTF-8 mode in the parent directory. Installing GT.M generates both versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed, and you choose the option to install UTF-8 mode support. Note that on 64-bit versions of GT.M, the object code is in shared libraries, rather than individual files in the directory.

    • 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 file gtmprofile, 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_V6.3-003A_i686, then gtmprofile sets $gtm_dist to /usr/lib/fis-gtm/gtm_V6.3-003A_i686/utf8).

        • On platforms where the object files have not been placed in a libgtmutil.so shared library, 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. On platforms where the object files are in libgtmutil.so, that shared library is the one with the object files compiled in the mode for the process.

    For more information on gtmprofile, refer to the Basic Operations chapter of GT.M Administration and Operations Guide.

    Although GT.M uses ICU for UTF-8 operation, ICU is not FIS software and FIS does not support ICU.

    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.

    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or fail to position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on your specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    • GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis:

      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1),key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    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.

    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 as that provided by zlib.

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

    By default, GT.M searches for the libz.so shared library 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) or LD_LIBRARY_PATH (GNU/Linux) includes the directory containing 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.

    Although GT.M uses a library such as zlib for compression, such libraries are not FIS software and FIS does not support any compression libraries.

    V6.3-003B

    Fixes and enhancements specific to V6.3-003B:

    Id

    Prior Id

    Category

    Summary

    GTM-9020

    -

    DB

    Prevent problems when the LOCK space fills.

    GTM-9023

    -

    DB

    Fix rare, but serious issues with LOCKs by reverting GTM-8680

    V6.3-003A

    Fixes and enhancements specific to V6.3-003A:

    Id

    Prior Id

    Category

    Summary

    GTM-8880

    -

    Language

    Fix issue with (non-default) Standard Boolean evaluation with side-effects and certain patterns

    GTM-8887

    -

    Other

    Fix rare timer issue

    GTM-8889

    -

    Other

    Prevent UNDEF error after <CTRL-C> within ZHELP navigation

    V6.3-003

    Fixes and enhancements specific to V6.3-003:

    Id

    Prior Id

    Category

    Summary

    GTM-4212

    C9C03-001944

    Admin

    MUPIP better deals with over length file names

    GTM-6115

    C9I01-002944

    Language

    Please see GTM-8694

    GTM-7986

    -

    Language

    Warning on implicit wrapping of source lines exceeding maximum supported length

    GTM-8182

    -

    DB

    Allow updating globals belonging to different instances [!New Feature!]

    GTM-8186

    -

    Language

    Accept offset alone for an entryref in DO, GOTO and ZGOTO [!New Feature!]

    GTM-8587

    -

    Language

    Maintain $DEVICE and $KEY for all supported devices [!New Feature!]

    GTM-8617

    -

    Admin

    MUPIP SET supports N[ULL_SUBSCRIPTS] and STD[NULLCOLL] qualifiers. [!New Feature!]

    GTM-8680

    -

    DB

    [!alert!] LOCK Improvements

    GTM-8732

    -

    Admin

    Better validation for MUPIP REPLICATE -LOG_INTERVAL and -HELPER, and MUPIP SET -DEFER_TIME

    GTM-8735

    -

    Admin

    READ_ONLY characteristic to prevent state changes to MM databases [!New Feature!]

    GTM-8754

    -

    Other

    Prevent odd ASYNCIO deadlock

    GTM-8767

    -

    Admin

    [!alert!] MUPIP SET -HARD_SPIN_COUNT and -SPIN_SLEEP_MASK support [!New Feature!]

    GTM-8769

    -

    Language

    [!alert!] Syntax check $ETRAP, $ZSTEP, $ZTRAP, and EXCEPTION when specified [!New Feature!]

    GTM-8779

    -

    Admin

    Freeze Notification

    GTM-8780

    -

    Language

    Fix $SELECT() handling of certain syntax errors

    GTM-8781

    -

    Other

    Prevent memory leak in ZSYSTEM

    GTM-8786

    -

    Language

    [!alert!] $NAME() of a naked reference returns any current extended reference

    GTM-8787

    -

    Admin

    MUPIP JOURNAL -EXTRACT='-stdout' doesn't explode at termination if stdout is gone

    GTM-8788

    -

    Language

    The compiler excludes BLKTODEEP lines from the object files

    GTM-8789

    -

    Language

    Prevent NEW $ZGBLDIR from setting up an Update Process failure

    GTM-8790

    -

    DB

    Retain any extended first reference in $REFERENCE when sharing statistics

    GTM-8792

    C9I01-002944

    Language

    [!alert!] Prevent keys that exceed the supported maximum string length

    GTM-8794

    -

    Admin

    [!alert!] MUPIP RUNDOWN -OVERRIDE works on a non-MUPIP backup made during an Instance Freeze

    GTM-8795

    -

    DB

    Journal Updates promptly during MUPIP FREEZE -ONLINE

    GTM-8796

    -

    DB

    Improved error handling during TP and mini transaction commits

    GTM-8797

    -

    Admin

    Installation script fixes

    GTM-8798

    -

    Admin

    MUPIP ENDIANCVT converts Mutex Queue Slots

    GTM-8799

    -

    Other

    Improve performance for a pattern of local variable creation

    GTM-8801

    -

    Other

    cmake build produces appropriate support for the ^%YGBLSTATS utility.

    GTM-8804

    -

    Language

    ZSHOW "T" option to return summary for ZSHOW "GL" [!New Feature!]

    GTM-8805

    -

    DB

    Fix to havesting of LOCKs abandoned by an abnormally terminated process

    GTM-8832

    -

    Language

    Appropriately report NUMOFLOW for string literal with a huge value when used as a number

    GTM-8839

    -

    Language

    $DEVICE shows the full error message [!New Feature!]

    GTM-8840

    -

    Admin

    [!alert!] Normalized gtmsecshr message severities

    GTM-8842

    -

    Admin

    ZBREAK and ZSTEP restricted in triggers when TRIGGER_MOD is restricted [!New Feature!]

    GTM-8844

    -

    Admin

    [!alert!] Restriction available for HALT and ZHALT; ZGOTO 0 can return a non-zero status to the shell [!New Feature!]

    GTM-8846

    -

    Admin

    GT.M accepts multi-slash journal file names

    GTM-8847

    -

    Language

    Provide a way to detect and limit process private heap storage [!New Feature!]

    GTM-8849

    -

    Other

    Help databases built with make files have QDBRUNDOWN and NOGVSTATS characteristics

    GTM-8850

    -

    DB

    Allow process exit when MUPIP FREEZE -ONLINE is in place

    GTM-8854

    -

    Language

    Compiler handles a syntax error after a literal postconditional that's FALSE

    GTM-8855

    -

    Other

    Prevent memory leak from an error locating a global directory

    GTM-8856

    -

    Language

    Defer failing evaluations of literal pattern matches to run time

    GTM-8857

    -

    Language

    Improve error detection for certain pattern match cases

    GTM-8858

    -

    DB

    Improve available information in cases of apparent database integrity issues

    GTM-8866

    -

    Language

    Prevent timeouts with more than three decinal digits from being too long

    GTM-8873

    -

    DB

    Prevent occasional $ORDER(,-1) problem

    Database

    • GT.M allows updating globals belonging to a different source instance using extended global references or SET $ZGBLDIR. While the replication setup remains the same, these are the main considerations:

      1. Use one of two ways to identify the current instance as specified by a replication instance file:

        1. A global directory can define a mapping to a replication instance file as specified with a GDE CHANGE -INSTANCE -FILE_NAME=<replication_instance_file> command. When a global directory is use, if it has a mapping of an instance file, that mapping overrides any setting of the gtm_repl_instance environment variable. GDE CHANGE -INSTANCE -FILE_NAME="" removes any global directory mapping for an instance file.

        2. The gtm_repl_instance environment variable specifies a replication instance file for utilities, and, as the default, whenever a user processes relies on a global directory with no instance file specification.

      2. In order to use multiple instances, at least one global directory must have an instance mapping.

      3. A replication instance file cannot share any region with another instance file.

      4. The Source Servers of all the instances have properly set up Replication Journal Pools.

      5. A TP transaction or a trigger, as it always executes within a TP transaction, must always restrict updates to globals in one replicating instance.

      [Note]Notes

      • Like other mapping specified by a global directory, a process determines any instance mapping by a global directory at the time a process first uses uses the global directory. Processes other than MUPIP CREATE ignore other (non-mapping) global directory database characteristics, except for collation, which interacts with mapping.

      • When Instance Freeze is enabled (gtm_custom_errors is appropriately defined), a process attaches a region to an instance at the first access to the region; the access may be a read or a VIEW/$VIEW(). Otherwise, the process attaches to a region at the first update to that region. When the mappings are correct, this difference does not matter.

      • A process can always update globals that are not in a replicated region.

      • Use $VIEW("JNLPOOL") to determine the state of the current Journal Pool. $VIEW("JNLPOOL") returns the replication instance file name for the current Journal Pool and an empty string when there is no Journal Pool. Note that the current Journal Pool may not be associated with the last global accessed by an extended reference.

      Example:

      An EHR application uses a BC replication configuration (A->B) to provide continuous availability. There are two data warehouses for billing information and medical history. For research purposes, the data in these medical history warehouses is cleansed of patient identifiers. Two SI replication instances (P->Q) are setup for the two data warehouses.

      The primary global directory (specified via the environment variable gtmgbldir) includes the regions needed for the application proper. It may have the instance file as specified in the global directory or via the environment variable gtm_repl_instance. Each warehouse instance would have its own global directory (e.g. p.gld and q.gld). These global directories have an instance file specified with GDE CHANGE -INSTANCE -FILE_NAME=<replication_instance_file>.

      Such a replication setup may benefit from this facility in the following ways:

      1. A trigger on the primary database A uses normal global references to update a staging global (say ^%BACKLOG) in a non-replicated region of A to store information meant for the warehouses. At an appropriate time, a separate batch process runs across the ^%BACKLOG staging global and applies updates using extended references to P or Q using a transaction or non-TP. If the transaction succeeds, the process removes the applied updates from ^%BACKLOG. Locks control access to ^%BACKLOG and enforce the serialization of updates to P

        OR

      2. The application does not use triggers but updates a global on A in a transaction. If the transaction succeeds, the application starts two more transactions for the warehouses. The second transaction uses extended references to update P. If it fails, the application updates ^%BACKLOG("P") on a non-replicated region of A. The third transaction uses extended references to update Q. If it fails, the application updates ^%BACKLOG("Q") on a non-replicated region of A. A batch process runs periodically to apply updates from ^%BACKLOG to P and Q using TP or non-TP and remove updates that have been applied. This batch process uses LOCKs to control access and enforce serialization of updates to P and Q.

      Because this functionality has a wide variety of user stories (use cases) and has substantial complexity, although the code appears robust, we are not confident that we have exercised a sufficient breadth of use cases in our testing. Also, we may make changes in future releases that are not entirely backwards compatible. We encourage you to use this facility in development and testing, and to provide us with feedback. If you are an FIS customer and wish to use this in production, please contact us beforehand to discuss your use case(s). (GTM-8182) [!New Feature!]

    • GT.M LOCK commands perform better with large numbers of locks, and particularly with large numbers of processes acquiring the locks. Previously processes acquiring locks could encounter significant slowdown and lock timeouts as the number of locks and competing processes increased. This change requires additional memory per lock slot, so administrators should monitor lock slots (LKE SHOW) to determine if they need to increase lock space needs.

      The GDE -LOCK_SPACE segment qualifier and MUPIP SET -LOCK_SPACE qualifier accept a maximum value of 262144 pages. Previously the maximum value was 65536 pages.

      LKE SHOW includes a LOCKSPACEINFO message in its output for regions with a BG or MM access method. This message provides additional information on the use of LOCK space. Previously LKE only issued this message when the lock space was exhausted.

      (GTM-8680) [!Alert!]

    • When the first reference to a database for which a process has statistics sharing enabled is an extended reference, $REFERENCE maintains the extended reference. A regression associated with the implementation of statistics sharing in V6.3-001[A] caused this unusual case to lose that information. This was only ever observed in the GT.M development environment and has never been reported from a customer site. (GTM-8790)

    • GT.M keeps journal files up to date while a MUPIP FREEZE -ONLINE is in place. Previously the journal files would only be updated when there was a large amount of journal activity or the freeze was removed. (GTM-8795)

    • GT.M correctly handles any errors in the middle of a transaction commit. In GT.M V6.3-002, due to a regression introduced by GTM-8436, it was possible in very rare scenarios for a critical section deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8796)

    • GT.M manages LOCK concurrency correctly when checking for abandoned LOCKs. In V6.3-002 it could prematurely or belatedly determine that a LOCK was abandoned. (GTM-8805)

    • GT.M processes detach from database files correctly when a FREEZE -ONLINE is in place. Previously a process could hang waiting on a critical resource while trying to detach, which typically occurs when the process is trying to exit. (GTM-8850)

    • Improve available information in cases of apparent database integrity issues. (GTM-8858)

    • GT.M properly handles retries involving $ORDER(gvn,-1) or $ZPREVIOUS(gvn) functions. Previously, with certain key combinations, the retry processing could overflow a buffer, leading to memory corruption. The workaround was for any process using $$ORDER(,-1) in a region to previously have used a maximum length key for the region. (GTM-8873)

    • V63-003B GT.M handles out-of-lock-space conditions more gracefully. Previously a full lock table could result in corruption of the lock structures, leading to segmentation violations (SIG-11). (GTM-9020)

    • V63-003B This basically reverts GTM-8680 as the performance improvements were unreliable in circumstances reported by a customer, resulting in multiple processes occasionally holding the same LOCK. The GDE -LOCK_SPACE segment qualifier and MUPIP SET -LOCK_SPACE qualifier accept a maximum value of 65536 pages. In V6.3-003[A] the maximum value was 262144 pages. LKE SHOW does not include a LOCKSPACEINFO message in its output for regions with a BG or MM access method as it did in V6.3-003[A]; GT.M only issues this when the application exhausts the LOCK space. (GTM-9023)

    Language

    • Addressed by GTM-8694 (GTM-6115)

    • When GT.M encounters a line with a length greater than 8192 bytes in a source file, it emits a %GTM-W-LSINSERTED warning. This warning identifies cases where a line greater than 8192 bytes is split into multiple lines, which causes statements beyond the character prior to the limit to execute irrespective of any starting IF, ELSE or FOR commands. Previously, GT.M split the lines with no warning. (GTM-7986)

    • GT.M accepts an offset without a label for an entryref argument to DO, GOTO and ZGOTO. FIS recommends restricting the use of offsets in entryrefs to debugging, error handling and testing. Previously GT.M required a label before any offset. (GTM-8186) [!New Feature!]

    • GT.M sets $KEY to the characters terminating a READ, and NULL if terminated otherwise (e.g. FIX format, end of file, or timeout). When it encounters an error during an I/O, GT.M sets $DEVICE to "1," followed by an error description. Previously, GT.M did not maintain $KEY for sequential devices and only maintained $DEVICE for certain I/O errors. (GTM-8587) [!New Feature!]

    • GT.M checks the syntax of code assigned to $ETRAP, $ZSTEP, $ZTRAP, and EXCEPTION at the time they are specified. Note that $ZTRAP and EXCEPTION are subject to gtm_ztrap_form, and, if that specifies entryref or adaptive, GT.M does not check the syntax. Also, the environment variables $gtm_etrap, $gtm_trigger_etrap, and $gtm_zstep provide ways of setting some of the ISVs, so their values are verified at process initiation. Further, a SET $ETRAP uses a temporary default value of "IF $ZJOBEXAM" when shifting from $ZTRAP to $ETRAP in case the specified value has compilation errors. Previously GT.M detected errors in such code only for SET $ZSTEP and when attempting to use the vector. (GTM-8769) [!Alert!] [!New Feature!]

    • $SELECT() compilation properly handles special cases where an omitted colon after a literal true select argument produces a syntax error; a regression introduced in V6.3-001[A], caused it to produce a GTMASSERT2 after reporting the issue. (GTM-8780)

    • $NAME() of a naked reference returns any extended reference associated with the current $REFERENCE; previously it did not. (GTM-8786) [!Alert!]

    • The compiler excludes BLKTODEEP lines from the object files; due to a regression introduced by GTM-5178 in V6.3-002 they were not excluded (GTM-8788)

    • The Update Process operates correctly when a trigger issues a NEW $ZGBLDIR while performing updates on other unreplicated instances. A regression introduced with GTM-4759 in V63000[A] caused such operations in the Update Process to terminate unexpectedly with a segmentation fault (SIG-11). (GTM-8789)

    • $QUERY() of a local variable produces a MAXSTRLEN error when its result exceeds the supported string length. While GT.M supports very long key lengths for local variables, features that need to work with the entire key, such as $NAME() and $QUERY(), may not be able to handle keys with a length that exceeds the maximum supported string length (currently 1MiB). Rather than prohibit longer keys entirely, GT.M just restricts such features, so, if you need the features, avoid keys that exceed the limit. Previously $QUERY() could give a segmentation violation (SIG-11) if it encountered an over-length key. (GTM-6115)(GTM-8792) [!Alert!]

    • The ZSHOW "T" (where "T" can be case-insensitive) produces only the summary lines for "G" and "L" output; previously ZSHOW always showed the detail with the summary. (GTM-8804) [!New Feature!]

    • GT.M reports a NUMOFLOW error for a string literal used as a number and evaluating to a number that exceeds the supported range, as of this writing: 1E47. A compiler optimization in V6.3-001[A] caused such an evaluation to produce a very very small negative value. (GTM-8832)

    • $DEVICE returns the complete error message. Previously, $DEVICE truncated messages which were over 80 characters. (GTM-8839) [!New Feature!]

    • The read/write (non-NEWable) $ZSTRPLLIM ISV provides a way for a process to limit its process private memory used for local variable and scratch storage. When the value is zero (0), the default, or negative, there is no limit. A positive value specifies a byte limit. When a request for additional memory exceeds the limit, GT.M does the expansion, and then produces an STPCRIT error. By default, a later request for memory produces an STPOFLOW, unless, subsequent to STPCRIT, $ZSTRPLLIM has been set to the same or higher limit. Note that GT.M allocates memory in large blocks so the interaction of $ZSTRPLLIM with memory growth is not exact. When the gtm_string_pool_limit environment variable specifies a positive value, GT.M uses it for the initial value of $ZSTRPLLIM. Previously, process memory was only limited by operating system configuration. (GTM-8847) [!New Feature!]

    • The compiler appropriately handles a syntax error in the argument of a postconditional command when the postconditional is a literal that evaluates to FALSE. Due to a regression associated with GTM-8573 in V6.3-001[A], this combination caused an abnormal termination with a segmentation violation (SIG-11). (GTM-8854)

    • GT.M defers literal optimizations involving patterns within an XECUTE as well as evaluations that encounter issues with the pattern table. Due to a regression associated with GTM-8573 in V6.3-001[A], these combinations caused an abnormal termination with a segmentation violation (SIG-11). (GTM-8856)

    • Pattern code processing appropriately produces a PATMAXLEN error for certain patterns that exceed the size GT.M supports. Previously, some patterns produced a segmentation violation (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8857)

    • GT.M appropriately handles timeout values which have more than three decimal digits; in V6.3-002 and V6.3-003, such values inappropriately had a very long timeout. The workaround was to avoid such values because GT.M only recognizes three digits after the decimal point for timeouts. (GTM-8866)

    • V63-003A When using standard Boolean evaluation (no short-circuiting enabled by $gtm_boolean or gtm_side_effects) GT.M deals appropriately with cases where the there is a side effect and an right-hand operand interior to the expression happens to evaluate to a value that causes an incorrect result. This issue appeared with the introduction of standard Boolean evaluation in V5.5-000, and has not previously shown up in testing or been reported until a customer encountered a case. (GTM-8880)

    System Administration

    • MUPIP BACKUP for directory and file name lengths equal and greater than 255, issues FILENAMETOOLONG error; previously, this produced a core. Also, backing up an Instance File to a path longer than 255 succeeds with the correct journal sequence number; previously, this issued an incorrect journal sequence number. In addition, MUPIP JOURNAL -RECOVER -REDIRECT issues more information for the INVREDIRQUAL error; previously, it provided less context for the INVREDIRQUAL error. (GTM-4212)

    • The MUPIP SET command supports the following qualifiers: -N[ULL_SUBSCRIPTS]={never, always, existing}, which controls whether GT.M accepts null subscripts for database keys. -[NO]STD[NULLCOLL], which determines whether GT.M will use standard MUMPS collation or GT.M collation for null-subscripted keys. Previously, this functionality was only available through GDE for database file creation, and DSE for existing database files. FIS strongly recommends avoiding the use of DSE when there is an alternative. (GTM-8617) [!New Feature!]

    • MUPIP REPLICATE -RECEIVER -LOG_INTERVAL= and MUPIP SET -DEFER_TIME= accept values ranging from 0 to 2**31-1, -DEFER_TIME= accepts one special value -1; otherwise they produce an error message. MUPIP REPLICATE -RECEIVER -HELPER accepts values ranging from 1 to 128 and otherwise produces an error message. Previously, all these operations accepted inappropriate values. (GTM-8732)

    • MUPIP SET -{FILE|REGION} recognizes the -[NO]READ_ONLY qualifier to indicate whether GT.M should treat an MM access method segment as read only for all users, including root. This designation augments UNIX authorizations and prevents any state updates that normally might require an operational action for a database with no current accessing (attached) processes. The GT.M help databases have -READ_ONLY set by default. Previously, a database such as the gtmhelp database in the GT.M distribution typically never received a data update but nevertheless could require a ROLLBACK, RECOVER or RUNDOWN to ensure a proper at-rest state. MUPIP emits an error on attempts to set -READ_ONLY on databases with the BG access method, or to set the access method to BG on databases with -READ_ONLY set. (GTM-8735) [!New Feature!]

    • MUPIP SET for file or region accepts -H[ARD_SPIN_COUNT]=<integer count> and -SPIN[_SLEEP_MASK]=<hexadecimal mask>; previously it did not support changes to the hard spin count and required -SPIN_SLEEP_LIMIT to change the spin sleep mask. MUPIP SET no longer supports the -SPIN_SLEEP_LIMIT qualifier.(GTM-8767) [!Alert!] [!New Feature!]

    • MUPIP FREEZE sends a DBFREEZEON/DBFREEZEOFF message to the system log for each region whose freeze state is changed. (GTM-8779)

    • MUPIP JOURNAL -EXTRACT='-stdout' appropriately handles its termination; previously, if stdout was already closed this specification produced a segmentation violation (SIG-11). (GTM-8787)

    • Copies of a database file made while a MUPIP FREEZE -ONLINE -ON is in effect can be used on the same system by performing a MUPIP RUNDOWN -OVERRIDE and a MUPIP FREEZE -OFF on the copy. Previously, an attempt to remove the freeze on the copy would attempt to modify the journal files of the original database and fail. Note that this change moved the ^%PEEKBYNAME item "sgmnt_data.freeze_online" to "node_local.freeze_online"; for this release (V6.3-003) only, ^%PEEKBYNAME recognizes either designation, but going forward, it will not. If you have code referencing this item, please revise it. (GTM-8794) [!Alert!]

    • The gtminstall script has a new command line option to skip disablingRemoveIPC=Yes in systemd configuration files. This option was added to facilitate unattended installs and automated builds. Previously, if noresponse was provided, the script would terminate with an error in the script. This issue was only observed in the GT.M development environment, and was never reported by a user.

      The configure script better handles the detection of 64 bit software. Previously, the script could mistakenly identify 32bit software as 64bit software if the output of the file command contained "64" in the sha1 binary hash. This issue was only observed in the GT.M development environment, and was never reported by a user.

      Additionally the gtminstall script defaults to i586 kit for i686 platforms. Since GT.M V6.2-001, the GT.M release distribution kit has i586 in the name. Attempting to use gtminstall on an i686 platform resulted in a failure to download and install the distribution kit due to this change in name. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8797)

    • MUPIP ENDIANCVT converts all numeric file header fields to the opposite endian. Previously, it did not convert the Mutex Queue Slots field. (GTM-8798)

    • gtmsecshr, and facilities that interact with it use message severities that seem appropriate to the issue. Previously, we received customer concerns that the severities were arbitrary, which complicated understanding them. Note that, should you use message parsing that depends on severity, you should review it for possible impact. (GTM-8840) [!Alert!]

    • When TRIGGER_MOD is restricted, attempting to ZBREAK a trigger results in a RESTRICTEDOP error, and both ZBREAK and ZSTEP actions are ignored while executing code within a trigger. Previously a TRIGGER_MOD restriction did not imply these other restrictions. (GTM-8842) [!New Feature!]

    • The GT.M restrictions facility recognizes HALT[:<group-name>] and ZHALT[:<group-name>]. When either is present and restriction conditions are met, the restricted command produces a RESTRICTEDOP error. In order to limit pathological looping, if A GT.M process issues a second occurrence of the restricted command within half a second, it terminates after sending a fatal error to both the principal device and the syslog, and also producing a GTM_FATAL* context file, but no core file. Note that, With these restrictions in place, a process should terminate with, for example: ZGOTO 0. with or without a restriction, executing these commands as part triggered logic on a replicating instance may cause the Update Server to terminate and thereby stop replication. As part of this change when ""=$ZTRAP and ""!=$ECODE, ZGOTO 0 returns a non-zero status, derived from the error code in $ZSTATUS, to the shell. If you have an application that uses ZHALT, ZGOTO 0 and shell scripts that check returned status, you should review things in light of this change. Note: with appropriate error handling, an application can use one or both of these restrictions to perform clean up after any explicit HALT or ZHALT. Previously, the restrictions facility did not support these two restrictions, and $ZGOTO 0 always returned a success status to the shell. (GTM-8844) [!Alert!] [!New Feature!]

    • GT.M appropriately uses file paths with multiple adjacent forward slashes (/) when turning journaling on. Previously, when turning journaling on, GT.M appended inappropriate characters to the end of intended journal file names whose path contained adjacent forward slashes. The workaround was to avoid specifying file paths with any adjacent forward slashes. (GTM-8846)

    Other

    • GT.M defers interrupts during asynchronous database writes. Previously, such interrupts could very occasionally cause a deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8754)

    • ZSYSTEM manages memory appropriately; a regression in V6.3-002 caused it to leak small amounts of memory. This issue was only observed in the GT.M development environment, and was not reported by a user. (GTM-8781)

    • GT.M handles certain unusual cases of local storage (heap) utilization more efficiently. Previously, these cases would cause poor performance as local when adding variables with such patterns. (GTM-8799)

    • The cmake build produces appropriate support for the ^%YGBLSTATS utility; in the original V6.3-001, V6.3-001A and V6.3-002 releases, an attempt to use ^%YGBLSTATS with a cmake build produced DLLNORTN and ZCRTENOTF errors.(GTM-8801)

    • Help databases built with make files have QDBRUNDOWN and NOGVSTATS characteristics, which match the properties of help databases of the release builds. Previously, these characteristics differed depending on the build. (GTM-8849)

    • GT.M correctly cleans up buffers which were allocated prior to a runtime error due to a missing global directory. Previously, these buffers would accumulate if an error handler prevented GT.M from terminating. The workaround for this was to avoid repeated attempts to use a global directory that does not exist or to which the process does not have an authorized path. (GTM-8855)

    • V63-003A GT.M handles rare cases in timer handling correctly. Previously these cases could result in SETITIMERFAILED errors and messages in the system log. This was only ever observed in the GT.M development environment and has never been reported from a customer site. (GTM-8887)

    • V63-003A The ZHELP command does not report errors after the user presses a <CTRL-C>. Previously, when exiting after a <CTRLC>, the utility reported an UNDEF error and left a GT.M help dump file for analysis. (GTM-8889)

    Error and Other Messages

    DBFREEZEOFF New

    DBFREEZEOFF, +tar -xvf source.tar

  • Follow the instructions in the README.

    • Open Makefile with your editor; review and edit the common header (IFLAGS) and library paths (LIBFLAGS) in the Makefile to reflect those on your system.

    • Define the gtm_dist environment variable to point to the absolute path for the directory where you have GT.M installed

    • Copy and paste the commands from the README to compile and install the encryption plugin with the permissions defined at install time

      [Caution]Caution

      There are separate steps to compile the encryption plugin for GT.M versions V5.3-004 through V6.3-000 when OpenSSL 1.1 is installed and OpenSSL 1.0.x libraries arestill available.

      • Download the most recent OpenSSL 1.0.x version

      • Compile and install (default installs to /usr/local/ssl)

        ./config && make install

      • Adjust the configuration : Move the newly installed libraries out of the way

        mv /usr/local/ssl/lib /usr/local/ssl/lib.donotuse

      • Adjust the configuration : Create another /usr/local/ssl/lib and symlink the existing 1.0.x library into it as the default. This ensures that the encryption plugin is compiled using the compatible OpenSSL 1.0.x library. Adjust the path below as necessary.

        mkdir /usr/local/ssl/lib && ln -s /path/to/existing/libssl.so.1.0.x /usr/local/ssl/libssl.so

      • Recompile the encryption plugin following existing directions above

      • Remove /usr/local/ssl to avoid future complications

    • Upgrading to GT.M V6.3-003A

    The GT.M database consists of four types of components- database files, journal files, global directories, and replication instance files. The format of some database components differs for 32-bit and 64-bit GT.M releases for the x86 GNU/Linux platform.

    GT.M upgrade procedure for V6.3-003A consists of 5 stages:

    Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V6.3-003A depends on your GT.M upgrade history and your current version.

    Stage 1: Global Directory Upgrade

    FIS strongly recommends you back up your Global Directory file before upgrading. There is no one-step method for downgrading a Global Directory file to an older format.

    To upgrade from any previous version of GT.M:

    • Open your Global Directory with the GDE utility program of GT.M V6.3-003A.

    • Execute the EXIT command. This command automatically upgrades the Global Directory.

    To switch between 32- and 64-bit global directories on the x86 GNU/Linux platform:

    1. Open your Global Directory with the GDE utility program on the 32-bit platform.

    2. On GT.M versions that support SHOW -COMMAND, execute SHOW -COMMAND -FILE=file-name. This command stores the current Global Directory settings in the specified file.

    3. On GT.M versions that do not support GDE SHOW -COMMAND, execute the SHOW -ALL command. Use the information from the output to create an appropriate command file or use it as a guide to manually enter commands in GDE.

    4. Open GDE on the 64-bit platform. If you have a command file from 2. or 3., execute @file-name and then run the EXIT command. These commands automatically create the Global Directory. Otherwise use the GDE output from the old Global Directory and apply the settings in the new environment.

    An analogous procedure applies in the reverse direction.

    If you inadvertently open a Global Directory of an old 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 to downgrade to an old GT.M release:

    • Open the global directory with the GDE utility program of V6.3-003A.

    • Execute the SHOW -COMMAND -FILE=file-name command. This command stores the current Global Directory settings in the file-name command file. If the old version is significantly out of date, edit the command file to remove the commands that do not apply to the old format. Alternatively, you can use the output from SHOW -ALL or SHOW -COMMAND as a guide to manually enter equivalent GDE commands for the old version.

    Stage 2: Database Files Upgrade

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

    A V6 database file is a superset of a V5 database file and has potentially longer keys and records. Therefore, upgrading a database file requires no explicit procedure. After upgrading the Global Directory, opening a V5 database with a V6 process automatically upgrades fields in the database fileheader.

    A database created with V6 supports up to 992Mi blocks and is not backward compatible. V6 databases that take advantage of V6 limits on key size and records size cannot be downgraded. Use MUPIP DOWNGRADE -VERSION=V5 to downgrade a V6 database back to V5 format provided it meets the database downgrade requirements. For more information on downgrading a database, refer to Downgrading to V5 or V4.

    [Important] Important

    A V5 database that has been automatically upgraded to V6 can perform all GT.M V6.3-003A operations. However, that database can only grow to the maximum size of the version in which it was originally created. A database created on V5.0-000 through V5.3-003 has maximum size of 128Mi blocks. A database created on V5.4-000 through V5.5-000 has a maximum size of 224Mi blocks. A database file created with V6.0-000 (or above) can grow up to a maximum of 992Mi blocks. This means that, for example, the maximum size of a V6 database file having 8KiB block size is 7936GiB (8KiB*992Mi).

    [Important] Important

    In order to perform a database downgrade you must perform a MUPIP INTEG -NOONLINE. If the duration of the MUPIP INTEG exceeds the time allotted for an upgrade you should rely on a rolling upgrade scheme using replication.

    If your database has any previously used but free blocks from an earlier upgrade cycle (V4 to V5), you may need to execute the MUPIP REORG -UPGRADE command. If you have already executed the MUPIP REORG -UPGRADE command in a version prior to V5.3-003 and if subsequent versions cannot determine whether MUPIP REORG -UPGRADE performed all required actions, it sends warnings to the syslog requesting another run of MUPIP REORG -UPGRADE. In that case, perform any one of the following steps:

    • Execute the MUPIP REORG -UPGRADE command again, or

    • Execute the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command to stop the warnings.

    [Caution] Caution

    Do not run the DSE CHANGE -FILEHEADER -FULLY_UPGRADED=1 command unless you are absolutely sure of having previously run a MUPIP REORG -UPGRADE from V5.3-003 or later. An inappropriate DSE CHANGE -FILEHEADE -FULLY_UPGRADED=1 may lead to database integrity issues.

    You do not need to run MUPIP REORG -UPGRADE on:

    • A database that was created by a V5 MUPIP CREATE

    • A database that has been completely processed by a MUPIP REORG -UPGRADE from V5.3-003 or later.

    For additional upgrade considerations, refer to Database Compatibility Notes.

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

    You need to upgrade your database files only when there is a block format upgrade from V4 to V5. However, some versions, for example, database files 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.

    • 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.

    • Run the MUPIP REORG -UPGRADE command. This command upgrades all V4 blocks to V5 format.

    [Note] Note

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

    Database Compatibility Notes

    • Changes to the database file header may occur in any release. GT.M automatically upgrades database file headers as needed. Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.

    • Databases created with V5.3-004 through V5.5-000 can grow to a maximum size of 224Mi (234,881,024) blocks. This means, for example, that with an 8KiB block size, the maximum database file size is 1,792GiB; this is effectively the size of a single global variable that has a region to itself and does not itself span regions; a database consists of any number of global variables. A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128Mi to 224Mi blocks.

    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128Mi (134, 217,728) blocks. GT.M versions V5.0-000 through V5.3-003 can access databases created with V5.3-004 and later as long as they remain within a 128Mi block limit.

    • Database created with V6.0-000 or above have a maximum size of 1,040,187,392(992Mi) blocks.

    • For information on downgrading a database upgraded from V6 to V5, refer to: Downgrading to V5 or V4.

    Stage 3: Replication Instance File Upgrade

    V6.3-003A does not require new replication instance files if you are upgrading from V5.5-000. However, V6.3-003A requires new replication instance files if you are upgrading from any version prior to V5.5-000. Instructions for creating new replication instance files are in the Database Replication chapter of the GT.M Administration and Operations Guide. Shut down all Receiver Servers on other instances that are to receive updates from this instance, shut down this instance Source Server(s), recreate the instance file, restart the Source Server(s) and then restart any Receiver Server for this instance with the -UPDATERESYNC qualifier.

    [Note] 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.

    [Important] Important

    You must always follow the steps described in the Database Replication chapter of the GT.M Administration and Operations Guide when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

    Stage 4: Journal Files Upgrade

    On every GT.M upgrade:

    • Create a fresh backup of your database.

    • Generate new journal files (without back-links).

    [Important] Important

    This is necessary because MUPIP JOURNAL cannot use journal files from a release other than its own for RECOVER, ROLLBACK, or EXTRACT.

    Stage 5: Trigger Definitions Upgrade

    If you are upgrading from V5.4-002A/V5.4-002B/V5.5-000 to V6.3-003A and you have database triggers defined in V6.2-000 or earlier, you need to ensure that your trigger definitions are wholesome in the older version and then run MUPIP TRIGGER -UPGRADE. If you have doubts about the wholesomeness of the trigger definitions in the old version use the instructions below to capture the definitions delete them in the old version (-*), run MUPIP TRIGGER -UPGRADE in V6.3-003A and then reload them as described below.

    You need to extract and reload your trigger definitions only if you are upgrading from V5.4-000/V5.4-000A/V5.4-001 to V6.3-003A or if you find your prior version trigger definitions have problems. For versions V5.4-000/V5.4-000A/V5.4-001 this is necessary because multi-line XECUTEs for triggers require a different internal storage format for triggers which makes triggers created in V5.4-000/V5.4-000A/V5.4-001 incompatible with V5.4-002/V5.4-002A/V5.4-002B/V5.5-000/V6.0-000/V6.0-001/V6.3-003A.

    To extract and reapply the trigger definitions on V6.3-003A using MUPIP TRIGGER:

    1. Using the old version, execute a command like mupip trigger -select="*" trigger_defs.trg. Now, the output file trigger_defs.trg contains all trigger definitions.

    2. Place -* at the beginning of the trigger_defs.trg file to remove the old trigger definitions.

    3. Using V6.3-003A, run mupip trigger -triggerfile=trigger_defs.trg to reload your trigger definitions.

    To extract and reload trigger definitions on a V6.3-003A replicating instance using $ZTRIGGER():

    1. Shut down the instance using the old version of GT.M.

    2. Execute a command like mumps -run %XCMD 'i $ztrigger("select")' > trigger_defs.trg . Now, the output file trigger_defs.trg contains all trigger definitions.

    3. Turn off replication on all regions.

    4. Run mumps -run %XCMD 'i $ztrigger("item","-*") to remove the old trigger definitions.

    5. Perform the upgrade procedure applicable for V6.3-003A.

    6. Run mumps -run %XCMD 'if $ztrigger("file","trigger_defs.trg")' to reapply your trigger definitions.

    7. Turn replication on.

    8. Connect to the originating instance.

    [Note] Note

    Reloading triggers renumbers automatically generated trigger names.

    Downgrading to V5 or V4

    You can downgrade a GT.M V6 database to V5 or V4 format using MUPIP DOWNGRADE.

    Starting with V6.0-000, MUPIP DOWNGRADE supports the -VERSION qualifier with the following format: 

    MUPIP DOWNGRADE -VERSION=[V5|V4]

    -VERSION specifies the desired version for the database header.

    To qualify for a downgrade from V6 to V5, your database must meet the following requirements:

    1. The database was created with a major version no greater than the target version.

    2. The database does not contain any records that exceed the block size (spanning nodes).

    3. The sizes of all the keys in database are less than 256 bytes.

    4. There are no keys present in database with size greater than the Maximum-Key-Size specification in the database header, that is, Maximum-Key-Size is assured.

    5. The maximum Record size is small enough to accommodate key, overhead, and value within a block.

    To verify that your database meets all of the above requirements, execute MUPIP INTEG -NOONLINE. Note that the integrity check requires the use of -NOONLINE to ensure no concurrent updates invalidate the above requirements. Once assured that your database meets all the above requirements, MUPIP DOWNGRADE -VERSION=V5 resets the database header to V5 elements which makes it compatible with V5 versions.

    To qualify for a downgrade from V6 to V4, your database must meet the same downgrade requirements that are there for downgrading from V6 to V5.

    If your database meets the downgrade requirements, perform the following steps to downgrade to V4:

    1. In a GT.M V6.3-003A environment:

      1. Execute MUPIP SET -VERSION=v4 so that GT.M writes updates blocks in V4 format.

      2. Execute MUPIP REORG -DOWNGRADE to convert all blocks from V6 format to V4 format.

    2. Bring down all V6 GT.M processes and execute MUPIP RUNDOWN -FILE on each database file to ensure that there are no processes accessing the database files.

    3. Execute MUPIP DOWNGRADE -VERSION=V4 to change the database file header from V6 to V4.

    4. Restore or recreate all the V4 global directory files.

    5. Your database is now successfully downgraded to V4.

    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(R) (ISO/IEC-10646) character strings. On a system that does not have ICU 3.6 or later installed, GT.M only supports M mode.

    On a system that has ICU installed, GT.M optionally 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 it finds both a source and an object file, and the object predates the source file and was generated with the same setting of $gtm_chset/$ZCHset. A GT.M process generates 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 UTF-8 mode in the utf8 subdirectory, and one compiled without support for UTF-8 mode in the parent directory. Installing GT.M generates both versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed, and you choose the option to install UTF-8 mode support. Note that on 64-bit versions of GT.M, the object code is in shared libraries, rather than individual files in the directory.

    • 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 file gtmprofile, 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_V6.3-003A_i686, then gtmprofile sets $gtm_dist to /usr/lib/fis-gtm/gtm_V6.3-003A_i686/utf8).

        • On platforms where the object files have not been placed in a libgtmutil.so shared library, 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. On platforms where the object files are in libgtmutil.so, that shared library is the one with the object files compiled in the mode for the process.

    For more information on gtmprofile, refer to the Basic Operations chapter of GT.M Administration and Operations Guide.

    Although GT.M uses ICU for UTF-8 operation, ICU is not FIS software and FIS does not support ICU.

    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.

    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or fail to position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on your specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    • GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis:

      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1),key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    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.

    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 as that provided by zlib.

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

    By default, GT.M searches for the libz.so shared library 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) or LD_LIBRARY_PATH (GNU/Linux) includes the directory containing 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.

    Although GT.M uses a library such as zlib for compression, such libraries are not FIS software and FIS does not support any compression libraries.

    V6.3-003B

    Fixes and enhancements specific to V6.3-003B:

    Id

    Prior Id

    Category

    Summary

    GTM-9020

    -

    DB

    Prevent problems when the LOCK space fills.

    GTM-9023

    -

    DB

    Fix rare, but serious issues with LOCKs by reverting GTM-8680

    V6.3-003A

    Fixes and enhancements specific to V6.3-003A:

    Id

    Prior Id

    Category

    Summary

    GTM-8880

    -

    Language

    Fix issue with (non-default) Standard Boolean evaluation with side-effects and certain patterns

    GTM-8887

    -

    Other

    Fix rare timer issue

    GTM-8889

    -

    Other

    Prevent UNDEF error after <CTRL-C> within ZHELP navigation

    V6.3-003

    Fixes and enhancements specific to V6.3-003:

    Id

    Prior Id

    Category

    Summary

    GTM-4212

    C9C03-001944

    Admin

    MUPIP better deals with over length file names

    GTM-6115

    C9I01-002944

    Language

    Please see GTM-8694

    GTM-7986

    -

    Language

    Warning on implicit wrapping of source lines exceeding maximum supported length

    GTM-8182

    -

    DB

    Allow updating globals belonging to different instances [!New Feature!]

    GTM-8186

    -

    Language

    Accept offset alone for an entryref in DO, GOTO and ZGOTO [!New Feature!]

    GTM-8587

    -

    Language

    Maintain $DEVICE and $KEY for all supported devices [!New Feature!]

    GTM-8617

    -

    Admin

    MUPIP SET supports N[ULL_SUBSCRIPTS] and STD[NULLCOLL] qualifiers. [!New Feature!]

    GTM-8680

    -

    DB

    [!alert!] LOCK Improvements

    GTM-8732

    -

    Admin

    Better validation for MUPIP REPLICATE -LOG_INTERVAL and -HELPER, and MUPIP SET -DEFER_TIME

    GTM-8735

    -

    Admin

    READ_ONLY characteristic to prevent state changes to MM databases [!New Feature!]

    GTM-8754

    -

    Other

    Prevent odd ASYNCIO deadlock

    GTM-8767

    -

    Admin

    [!alert!] MUPIP SET -HARD_SPIN_COUNT and -SPIN_SLEEP_MASK support [!New Feature!]

    GTM-8769

    -

    Language

    [!alert!] Syntax check $ETRAP, $ZSTEP, $ZTRAP, and EXCEPTION when specified [!New Feature!]

    GTM-8779

    -

    Admin

    Freeze Notification

    GTM-8780

    -

    Language

    Fix $SELECT() handling of certain syntax errors

    GTM-8781

    -

    Other

    Prevent memory leak in ZSYSTEM

    GTM-8786

    -

    Language

    [!alert!] $NAME() of a naked reference returns any current extended reference

    GTM-8787

    -

    Admin

    MUPIP JOURNAL -EXTRACT='-stdout' doesn't explode at termination if stdout is gone

    GTM-8788

    -

    Language

    The compiler excludes BLKTODEEP lines from the object files

    GTM-8789

    -

    Language

    Prevent NEW $ZGBLDIR from setting up an Update Process failure

    GTM-8790

    -

    DB

    Retain any extended first reference in $REFERENCE when sharing statistics

    GTM-8792

    C9I01-002944

    Language

    [!alert!] Prevent keys that exceed the supported maximum string length

    GTM-8794

    -

    Admin

    [!alert!] MUPIP RUNDOWN -OVERRIDE works on a non-MUPIP backup made during an Instance Freeze

    GTM-8795

    -

    DB

    Journal Updates promptly during MUPIP FREEZE -ONLINE

    GTM-8796

    -

    DB

    Improved error handling during TP and mini transaction commits

    GTM-8797

    -

    Admin

    Installation script fixes

    GTM-8798

    -

    Admin

    MUPIP ENDIANCVT converts Mutex Queue Slots

    GTM-8799

    -

    Other

    Improve performance for a pattern of local variable creation

    GTM-8801

    -

    Other

    cmake build produces appropriate support for the ^%YGBLSTATS utility.

    GTM-8804

    -

    Language

    ZSHOW "T" option to return summary for ZSHOW "GL" [!New Feature!]

    GTM-8805

    -

    DB

    Fix to havesting of LOCKs abandoned by an abnormally terminated process

    GTM-8832

    -

    Language

    Appropriately report NUMOFLOW for string literal with a huge value when used as a number

    GTM-8839

    -

    Language

    $DEVICE shows the full error message [!New Feature!]

    GTM-8840

    -

    Admin

    [!alert!] Normalized gtmsecshr message severities

    GTM-8842

    -

    Admin

    ZBREAK and ZSTEP restricted in triggers when TRIGGER_MOD is restricted [!New Feature!]

    GTM-8844

    -

    Admin

    [!alert!] Restriction available for HALT and ZHALT; ZGOTO 0 can return a non-zero status to the shell [!New Feature!]

    GTM-8846

    -

    Admin

    GT.M accepts multi-slash journal file names

    GTM-8847

    -

    Language

    Provide a way to detect and limit process private heap storage [!New Feature!]

    GTM-8849

    -

    Other

    Help databases built with make files have QDBRUNDOWN and NOGVSTATS characteristics

    GTM-8850

    -

    DB

    Allow process exit when MUPIP FREEZE -ONLINE is in place

    GTM-8854

    -

    Language

    Compiler handles a syntax error after a literal postconditional that's FALSE

    GTM-8855

    -

    Other

    Prevent memory leak from an error locating a global directory

    GTM-8856

    -

    Language

    Defer failing evaluations of literal pattern matches to run time

    GTM-8857

    -

    Language

    Improve error detection for certain pattern match cases

    GTM-8858

    -

    DB

    Improve available information in cases of apparent database integrity issues

    GTM-8866

    -

    Language

    Prevent timeouts with more than three decinal digits from being too long

    GTM-8873

    -

    DB

    Prevent occasional $ORDER(,-1) problem

    Database

    • GT.M allows updating globals belonging to a different source instance using extended global references or SET $ZGBLDIR. While the replication setup remains the same, these are the main considerations:

      1. Use one of two ways to identify the current instance as specified by a replication instance file:

        1. A global directory can define a mapping to a replication instance file as specified with a GDE CHANGE -INSTANCE -FILE_NAME=<replication_instance_file> command. When a global directory is use, if it has a mapping of an instance file, that mapping overrides any setting of the gtm_repl_instance environment variable. GDE CHANGE -INSTANCE -FILE_NAME="" removes any global directory mapping for an instance file.

        2. The gtm_repl_instance environment variable specifies a replication instance file for utilities, and, as the default, whenever a user processes relies on a global directory with no instance file specification.

      2. In order to use multiple instances, at least one global directory must have an instance mapping.

      3. A replication instance file cannot share any region with another instance file.

      4. The Source Servers of all the instances have properly set up Replication Journal Pools.

      5. A TP transaction or a trigger, as it always executes within a TP transaction, must always restrict updates to globals in one replicating instance.

      [Note]Notes

      • Like other mapping specified by a global directory, a process determines any instance mapping by a global directory at the time a process first uses uses the global directory. Processes other than MUPIP CREATE ignore other (non-mapping) global directory database characteristics, except for collation, which interacts with mapping.

      • When Instance Freeze is enabled (gtm_custom_errors is appropriately defined), a process attaches a region to an instance at the first access to the region; the access may be a read or a VIEW/$VIEW(). Otherwise, the process attaches to a region at the first update to that region. When the mappings are correct, this difference does not matter.

      • A process can always update globals that are not in a replicated region.

      • Use $VIEW("JNLPOOL") to determine the state of the current Journal Pool. $VIEW("JNLPOOL") returns the replication instance file name for the current Journal Pool and an empty string when there is no Journal Pool. Note that the current Journal Pool may not be associated with the last global accessed by an extended reference.

      Example:

      An EHR application uses a BC replication configuration (A->B) to provide continuous availability. There are two data warehouses for billing information and medical history. For research purposes, the data in these medical history warehouses is cleansed of patient identifiers. Two SI replication instances (P->Q) are setup for the two data warehouses.

      The primary global directory (specified via the environment variable gtmgbldir) includes the regions needed for the application proper. It may have the instance file as specified in the global directory or via the environment variable gtm_repl_instance. Each warehouse instance would have its own global directory (e.g. p.gld and q.gld). These global directories have an instance file specified with GDE CHANGE -INSTANCE -FILE_NAME=<replication_instance_file>.

      Such a replication setup may benefit from this facility in the following ways:

      1. A trigger on the primary database A uses normal global references to update a staging global (say ^%BACKLOG) in a non-replicated region of A to store information meant for the warehouses. At an appropriate time, a separate batch process runs across the ^%BACKLOG staging global and applies updates using extended references to P or Q using a transaction or non-TP. If the transaction succeeds, the process removes the applied updates from ^%BACKLOG. Locks control access to ^%BACKLOG and enforce the serialization of updates to P

        OR

      2. The application does not use triggers but updates a global on A in a transaction. If the transaction succeeds, the application starts two more transactions for the warehouses. The second transaction uses extended references to update P. If it fails, the application updates ^%BACKLOG("P") on a non-replicated region of A. The third transaction uses extended references to update Q. If it fails, the application updates ^%BACKLOG("Q") on a non-replicated region of A. A batch process runs periodically to apply updates from ^%BACKLOG to P and Q using TP or non-TP and remove updates that have been applied. This batch process uses LOCKs to control access and enforce serialization of updates to P and Q.

      Because this functionality has a wide variety of user stories (use cases) and has substantial complexity, although the code appears robust, we are not confident that we have exercised a sufficient breadth of use cases in our testing. Also, we may make changes in future releases that are not entirely backwards compatible. We encourage you to use this facility in development and testing, and to provide us with feedback. If you are an FIS customer and wish to use this in production, please contact us beforehand to discuss your use case(s). (GTM-8182) [!New Feature!]

    • GT.M LOCK commands perform better with large numbers of locks, and particularly with large numbers of processes acquiring the locks. Previously processes acquiring locks could encounter significant slowdown and lock timeouts as the number of locks and competing processes increased. This change requires additional memory per lock slot, so administrators should monitor lock slots (LKE SHOW) to determine if they need to increase lock space needs.

      The GDE -LOCK_SPACE segment qualifier and MUPIP SET -LOCK_SPACE qualifier accept a maximum value of 262144 pages. Previously the maximum value was 65536 pages.

      LKE SHOW includes a LOCKSPACEINFO message in its output for regions with a BG or MM access method. This message provides additional information on the use of LOCK space. Previously LKE only issued this message when the lock space was exhausted.

      (GTM-8680) [!Alert!]

    • When the first reference to a database for which a process has statistics sharing enabled is an extended reference, $REFERENCE maintains the extended reference. A regression associated with the implementation of statistics sharing in V6.3-001[A] caused this unusual case to lose that information. This was only ever observed in the GT.M development environment and has never been reported from a customer site. (GTM-8790)

    • GT.M keeps journal files up to date while a MUPIP FREEZE -ONLINE is in place. Previously the journal files would only be updated when there was a large amount of journal activity or the freeze was removed. (GTM-8795)

    • GT.M correctly handles any errors in the middle of a transaction commit. In GT.M V6.3-002, due to a regression introduced by GTM-8436, it was possible in very rare scenarios for a critical section deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8796)

    • GT.M manages LOCK concurrency correctly when checking for abandoned LOCKs. In V6.3-002 it could prematurely or belatedly determine that a LOCK was abandoned. (GTM-8805)

    • GT.M processes detach from database files correctly when a FREEZE -ONLINE is in place. Previously a process could hang waiting on a critical resource while trying to detach, which typically occurs when the process is trying to exit. (GTM-8850)

    • Improve available information in cases of apparent database integrity issues. (GTM-8858)

    • GT.M properly handles retries involving $ORDER(gvn,-1) or $ZPREVIOUS(gvn) functions. Previously, with certain key combinations, the retry processing could overflow a buffer, leading to memory corruption. The workaround was for any process using $$ORDER(,-1) in a region to previously have used a maximum length key for the region. (GTM-8873)

    • V63-003B GT.M handles out-of-lock-space conditions more gracefully. Previously a full lock table could result in corruption of the lock structures, leading to segmentation violations (SIG-11). (GTM-9020)

    • V63-003B This basically reverts GTM-8680 as the performance improvements were unreliable in circumstances reported by a customer, resulting in multiple processes occasionally holding the same LOCK. The GDE -LOCK_SPACE segment qualifier and MUPIP SET -LOCK_SPACE qualifier accept a maximum value of 65536 pages. In V6.3-003[A] the maximum value was 262144 pages. LKE SHOW does not include a LOCKSPACEINFO message in its output for regions with a BG or MM access method as it did in V6.3-003[A]; GT.M only issues this when the application exhausts the LOCK space. (GTM-9023)

    Language

    • Addressed by GTM-8694 (GTM-6115)

    • When GT.M encounters a line with a length greater than 8192 bytes in a source file, it emits a %GTM-W-LSINSERTED warning. This warning identifies cases where a line greater than 8192 bytes is split into multiple lines, which causes statements beyond the character prior to the limit to execute irrespective of any starting IF, ELSE or FOR commands. Previously, GT.M split the lines with no warning. (GTM-7986)

    • GT.M accepts an offset without a label for an entryref argument to DO, GOTO and ZGOTO. FIS recommends restricting the use of offsets in entryrefs to debugging, error handling and testing. Previously GT.M required a label before any offset. (GTM-8186) [!New Feature!]

    • GT.M sets $KEY to the characters terminating a READ, and NULL if terminated otherwise (e.g. FIX format, end of file, or timeout). When it encounters an error during an I/O, GT.M sets $DEVICE to "1," followed by an error description. Previously, GT.M did not maintain $KEY for sequential devices and only maintained $DEVICE for certain I/O errors. (GTM-8587) [!New Feature!]

    • GT.M checks the syntax of code assigned to $ETRAP, $ZSTEP, $ZTRAP, and EXCEPTION at the time they are specified. Note that $ZTRAP and EXCEPTION are subject to gtm_ztrap_form, and, if that specifies entryref or adaptive, GT.M does not check the syntax. Also, the environment variables $gtm_etrap, $gtm_trigger_etrap, and $gtm_zstep provide ways of setting some of the ISVs, so their values are verified at process initiation. Further, a SET $ETRAP uses a temporary default value of "IF $ZJOBEXAM" when shifting from $ZTRAP to $ETRAP in case the specified value has compilation errors. Previously GT.M detected errors in such code only for SET $ZSTEP and when attempting to use the vector. (GTM-8769) [!Alert!] [!New Feature!]

    • $SELECT() compilation properly handles special cases where an omitted colon after a literal true select argument produces a syntax error; a regression introduced in V6.3-001[A], caused it to produce a GTMASSERT2 after reporting the issue. (GTM-8780)

    • $NAME() of a naked reference returns any extended reference associated with the current $REFERENCE; previously it did not. (GTM-8786) [!Alert!]

    • The compiler excludes BLKTODEEP lines from the object files; due to a regression introduced by GTM-5178 in V6.3-002 they were not excluded (GTM-8788)

    • The Update Process operates correctly when a trigger issues a NEW $ZGBLDIR while performing updates on other unreplicated instances. A regression introduced with GTM-4759 in V63000[A] caused such operations in the Update Process to terminate unexpectedly with a segmentation fault (SIG-11). (GTM-8789)

    • $QUERY() of a local variable produces a MAXSTRLEN error when its result exceeds the supported string length. While GT.M supports very long key lengths for local variables, features that need to work with the entire key, such as $NAME() and $QUERY(), may not be able to handle keys with a length that exceeds the maximum supported string length (currently 1MiB). Rather than prohibit longer keys entirely, GT.M just restricts such features, so, if you need the features, avoid keys that exceed the limit. Previously $QUERY() could give a segmentation violation (SIG-11) if it encountered an over-length key. (GTM-6115)(GTM-8792) [!Alert!]

    • The ZSHOW "T" (where "T" can be case-insensitive) produces only the summary lines for "G" and "L" output; previously ZSHOW always showed the detail with the summary. (GTM-8804) [!New Feature!]

    • GT.M reports a NUMOFLOW error for a string literal used as a number and evaluating to a number that exceeds the supported range, as of this writing: 1E47. A compiler optimization in V6.3-001[A] caused such an evaluation to produce a very very small negative value. (GTM-8832)

    • $DEVICE returns the complete error message. Previously, $DEVICE truncated messages which were over 80 characters. (GTM-8839) [!New Feature!]

    • The read/write (non-NEWable) $ZSTRPLLIM ISV provides a way for a process to limit its process private memory used for local variable and scratch storage. When the value is zero (0), the default, or negative, there is no limit. A positive value specifies a byte limit. When a request for additional memory exceeds the limit, GT.M does the expansion, and then produces an STPCRIT error. By default, a later request for memory produces an STPOFLOW, unless, subsequent to STPCRIT, $ZSTRPLLIM has been set to the same or higher limit. Note that GT.M allocates memory in large blocks so the interaction of $ZSTRPLLIM with memory growth is not exact. When the gtm_string_pool_limit environment variable specifies a positive value, GT.M uses it for the initial value of $ZSTRPLLIM. Previously, process memory was only limited by operating system configuration. (GTM-8847) [!New Feature!]

    • The compiler appropriately handles a syntax error in the argument of a postconditional command when the postconditional is a literal that evaluates to FALSE. Due to a regression associated with GTM-8573 in V6.3-001[A], this combination caused an abnormal termination with a segmentation violation (SIG-11). (GTM-8854)

    • GT.M defers literal optimizations involving patterns within an XECUTE as well as evaluations that encounter issues with the pattern table. Due to a regression associated with GTM-8573 in V6.3-001[A], these combinations caused an abnormal termination with a segmentation violation (SIG-11). (GTM-8856)

    • Pattern code processing appropriately produces a PATMAXLEN error for certain patterns that exceed the size GT.M supports. Previously, some patterns produced a segmentation violation (SIG-11). This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8857)

    • GT.M appropriately handles timeout values which have more than three decimal digits; in V6.3-002 and V6.3-003, such values inappropriately had a very long timeout. The workaround was to avoid such values because GT.M only recognizes three digits after the decimal point for timeouts. (GTM-8866)

    • V63-003A When using standard Boolean evaluation (no short-circuiting enabled by $gtm_boolean or gtm_side_effects) GT.M deals appropriately with cases where the there is a side effect and an right-hand operand interior to the expression happens to evaluate to a value that causes an incorrect result. This issue appeared with the introduction of standard Boolean evaluation in V5.5-000, and has not previously shown up in testing or been reported until a customer encountered a case. (GTM-8880)

    System Administration

    • MUPIP BACKUP for directory and file name lengths equal and greater than 255, issues FILENAMETOOLONG error; previously, this produced a core. Also, backing up an Instance File to a path longer than 255 succeeds with the correct journal sequence number; previously, this issued an incorrect journal sequence number. In addition, MUPIP JOURNAL -RECOVER -REDIRECT issues more information for the INVREDIRQUAL error; previously, it provided less context for the INVREDIRQUAL error. (GTM-4212)

    • The MUPIP SET command supports the following qualifiers: -N[ULL_SUBSCRIPTS]={never, always, existing}, which controls whether GT.M accepts null subscripts for database keys. -[NO]STD[NULLCOLL], which determines whether GT.M will use standard MUMPS collation or GT.M collation for null-subscripted keys. Previously, this functionality was only available through GDE for database file creation, and DSE for existing database files. FIS strongly recommends avoiding the use of DSE when there is an alternative. (GTM-8617) [!New Feature!]

    • MUPIP REPLICATE -RECEIVER -LOG_INTERVAL= and MUPIP SET -DEFER_TIME= accept values ranging from 0 to 2**31-1, -DEFER_TIME= accepts one special value -1; otherwise they produce an error message. MUPIP REPLICATE -RECEIVER -HELPER accepts values ranging from 1 to 128 and otherwise produces an error message. Previously, all these operations accepted inappropriate values. (GTM-8732)

    • MUPIP SET -{FILE|REGION} recognizes the -[NO]READ_ONLY qualifier to indicate whether GT.M should treat an MM access method segment as read only for all users, including root. This designation augments UNIX authorizations and prevents any state updates that normally might require an operational action for a database with no current accessing (attached) processes. The GT.M help databases have -READ_ONLY set by default. Previously, a database such as the gtmhelp database in the GT.M distribution typically never received a data update but nevertheless could require a ROLLBACK, RECOVER or RUNDOWN to ensure a proper at-rest state. MUPIP emits an error on attempts to set -READ_ONLY on databases with the BG access method, or to set the access method to BG on databases with -READ_ONLY set. (GTM-8735) [!New Feature!]

    • MUPIP SET for file or region accepts -H[ARD_SPIN_COUNT]=<integer count> and -SPIN[_SLEEP_MASK]=<hexadecimal mask>; previously it did not support changes to the hard spin count and required -SPIN_SLEEP_LIMIT to change the spin sleep mask. MUPIP SET no longer supports the -SPIN_SLEEP_LIMIT qualifier.(GTM-8767) [!Alert!] [!New Feature!]

    • MUPIP FREEZE sends a DBFREEZEON/DBFREEZEOFF message to the system log for each region whose freeze state is changed. (GTM-8779)

    • MUPIP JOURNAL -EXTRACT='-stdout' appropriately handles its termination; previously, if stdout was already closed this specification produced a segmentation violation (SIG-11). (GTM-8787)

    • Copies of a database file made while a MUPIP FREEZE -ONLINE -ON is in effect can be used on the same system by performing a MUPIP RUNDOWN -OVERRIDE and a MUPIP FREEZE -OFF on the copy. Previously, an attempt to remove the freeze on the copy would attempt to modify the journal files of the original database and fail. Note that this change moved the ^%PEEKBYNAME item "sgmnt_data.freeze_online" to "node_local.freeze_online"; for this release (V6.3-003) only, ^%PEEKBYNAME recognizes either designation, but going forward, it will not. If you have code referencing this item, please revise it. (GTM-8794) [!Alert!]

    • The gtminstall script has a new command line option to skip disablingRemoveIPC=Yes in systemd configuration files. This option was added to facilitate unattended installs and automated builds. Previously, if noresponse was provided, the script would terminate with an error in the script. This issue was only observed in the GT.M development environment, and was never reported by a user.

      The configure script better handles the detection of 64 bit software. Previously, the script could mistakenly identify 32bit software as 64bit software if the output of the file command contained "64" in the sha1 binary hash. This issue was only observed in the GT.M development environment, and was never reported by a user.

      Additionally the gtminstall script defaults to i586 kit for i686 platforms. Since GT.M V6.2-001, the GT.M release distribution kit has i586 in the name. Attempting to use gtminstall on an i686 platform resulted in a failure to download and install the distribution kit due to this change in name. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8797)

    • MUPIP ENDIANCVT converts all numeric file header fields to the opposite endian. Previously, it did not convert the Mutex Queue Slots field. (GTM-8798)

    • gtmsecshr, and facilities that interact with it use message severities that seem appropriate to the issue. Previously, we received customer concerns that the severities were arbitrary, which complicated understanding them. Note that, should you use message parsing that depends on severity, you should review it for possible impact. (GTM-8840) [!Alert!]

    • When TRIGGER_MOD is restricted, attempting to ZBREAK a trigger results in a RESTRICTEDOP error, and both ZBREAK and ZSTEP actions are ignored while executing code within a trigger. Previously a TRIGGER_MOD restriction did not imply these other restrictions. (GTM-8842) [!New Feature!]

    • The GT.M restrictions facility recognizes HALT[:<group-name>] and ZHALT[:<group-name>]. When either is present and restriction conditions are met, the restricted command produces a RESTRICTEDOP error. In order to limit pathological looping, if A GT.M process issues a second occurrence of the restricted command within half a second, it terminates after sending a fatal error to both the principal device and the syslog, and also producing a GTM_FATAL* context file, but no core file. Note that, With these restrictions in place, a process should terminate with, for example: ZGOTO 0. with or without a restriction, executing these commands as part triggered logic on a replicating instance may cause the Update Server to terminate and thereby stop replication. As part of this change when ""=$ZTRAP and ""!=$ECODE, ZGOTO 0 returns a non-zero status, derived from the error code in $ZSTATUS, to the shell. If you have an application that uses ZHALT, ZGOTO 0 and shell scripts that check returned status, you should review things in light of this change. Note: with appropriate error handling, an application can use one or both of these restrictions to perform clean up after any explicit HALT or ZHALT. Previously, the restrictions facility did not support these two restrictions, and $ZGOTO 0 always returned a success status to the shell. (GTM-8844) [!Alert!] [!New Feature!]

    • GT.M appropriately uses file paths with multiple adjacent forward slashes (/) when turning journaling on. Previously, when turning journaling on, GT.M appended inappropriate characters to the end of intended journal file names whose path contained adjacent forward slashes. The workaround was to avoid specifying file paths with any adjacent forward slashes. (GTM-8846)

    Other

    • GT.M defers interrupts during asynchronous database writes. Previously, such interrupts could very occasionally cause a deadlock. This issue was only observed in the GT.M development environment, and was never reported by a user. (GTM-8754)

    • ZSYSTEM manages memory appropriately; a regression in V6.3-002 caused it to leak small amounts of memory. This issue was only observed in the GT.M development environment, and was not reported by a user. (GTM-8781)

    • GT.M handles certain unusual cases of local storage (heap) utilization more efficiently. Previously, these cases would cause poor performance as local when adding variables with such patterns. (GTM-8799)

    • The cmake build produces appropriate support for the ^%YGBLSTATS utility; in the original V6.3-001, V6.3-001A and V6.3-002 releases, an attempt to use ^%YGBLSTATS with a cmake build produced DLLNORTN and ZCRTENOTF errors.(GTM-8801)

    • Help databases built with make files have QDBRUNDOWN and NOGVSTATS characteristics, which match the properties of help databases of the release builds. Previously, these characteristics differed depending on the build. (GTM-8849)

    • GT.M correctly cleans up buffers which were allocated prior to a runtime error due to a missing global directory. Previously, these buffers would accumulate if an error handler prevented GT.M from terminating. The workaround for this was to avoid repeated attempts to use a global directory that does not exist or to which the process does not have an authorized path. (GTM-8855)

    • V63-003A GT.M handles rare cases in timer handling correctly. Previously these cases could result in SETITIMERFAILED errors and messages in the system log. This was only ever observed in the GT.M development environment and has never been reported from a customer site. (GTM-8887)

    • V63-003A The ZHELP command does not report errors after the user presses a <CTRL-C>. Previously, when exiting after a <CTRLC>, the utility reported an UNDEF error and left a GT.M help dump file for analysis. (GTM-8889)

    Error and Other Messages

    DBFREEZEOFF New

    DBFREEZEOFF, Region rrrr is UNFROZEN ([NO]OVERRIDE [NO]AUTOREL)

    Operator log/MUPIP Information: The database region rrrr is no longer frozen, most likely due to a MUPIP FREEZE -OFF, with the selected options. [NO]AUTOREL indicates whether an autorelease of the region occurred prior to the MUPIP FREEZE -OFF command.

    Action: Confirm that this was the desired action.

    DBFREEZEON New

    DBFREEZEON, Region rrrr is FROZEN ([NO]OVERRIDE [NO]ONLINE [NO]AUTOREL)

    Operator log/MUPIP Information: The database region rrrr is frozen, most likely due to a MUPIP FREEZE -ON, with the reported options.

    Action: Confirm that this was the desired action.

    DBNONUMSUBS Revised

    DBNONUMSUBS, XXXX Key contains a numeric form of subscript in a global defined to collate all subscripts as strings

    Run Time/MUPIP Error: The record has a numeric subscript but the collation setting for the global or region indicates all subscripts are filed as strings. The leading context (XXXX) identifies the block and offest of the problematic record. This can arise if an operator uses DSE to force a change to a collation setting or to modify a key when the global already has content.

    Action: If you can determine the cause of, and reason for, the change and you may choose to reverse it. If you need to change the collation, the appropriate procedure is to EXTRACT the data, KILL the global, or remove and recreate the database file, and them LOAD the extracted data.

    DBNULCOL Revised

    DBNULCOL, diff --git a/articles/PIPE_IO_Technical_bulletin.html b/articles/PIPE_IO_Technical_bulletin.html index 0a0037d..5b9fbb4 100644 --- a/articles/PIPE_IO_Technical_bulletin.html +++ b/articles/PIPE_IO_Technical_bulletin.html @@ -51,23 +51,23 @@ SET p="Printer" OPEN p:(COMMAND="lp":WRITEONLY)::"PIPE"

    - Example 1 + Example 1

    Example 1 shows the use of a PIPE device to spool data to the default printer by spooling to the lp command, opened via the default shell (the shell specified by the SHELL environment variable, and the shell used to start GT.M if SHELL is unspecified). The WRITEONLY device parameter specifies that the GT.M process will not read data back from the lpr command.

    Example 2

                 Set p="MyProcs"
             OPEN p:(COMMAND="ps -ef|grep $USER":READONLY)::"PIPE"

    - Example 2 + Example 2

    Example 2 shows the use of a PIPE device to identify processes belonging to the current userid. The READONLY device parameter specifies that the GT.M process will only read the output of the pipe, and will not provide it with any input. This example illustrates the fact that the command can be any shell command, can include environment variables and pipes within the command.

    [Note]

    On your UNIX, flags to the ps command may differ from this example.

    Example 3:

                 Set p="Convert"
             OPEN p:(SHELL="/bin/csh":COMMAND="iconv -f ISO_8859-1 -t WINDOWS-1252")::"PIPE"

    - Example 3 + Example 3

    Example 3 shows the use of a process to whose input the GT.M process writes to and whose output the GT.M process reads back in, in this example convering data from an ISO 8859-1 encoding to the Windows 1252 encoding. This example also shows the use of a different shell from the default. If the OPEN deviceparameters don't specify a SHELL, the PIPE device uses the shell specified by the environment variable SHELL; if it does not find a definition for SHELL, the device uses the system default /bin/sh.

    Example 4:

                 SET p="Files"
             SET e="Errors"
             OPEN p:(COMMAND="find /var/log -type d -print":READONLY:STDERR=e)::"PIPE"

    - Example 4 + Example 4

    Example 4, GT.M uses the standard system utility find to obtain a list of subdirectories of /var/log, which are read back via the device with handle "Files" with any errors (e.g, “Permission denied” messages for sub-directories that the find command cannot process) read back via the device with handle "Errors".

    Return to top

    READ Command

    Return to top

    READ with no timeout

    A READ with no timeout reads whatever data is available to be read; if there is no data to be read, the process hangs until some data becomes available.

    Return to top

    READ with a timeout

    A READ with a timeout reads whatever data is available to be read, and returns; if there is no data to be read, the process waits for a maximum of the timeout period, an integer number of seconds, for data to become available (if the timeout is zero, it returns immediately, whether or not any data was read). If the READ returns before the timeout expires $Test, it set $TEST to TRUE(1); if the timeout expires, it sets $TEST to FALSE (0). When the READ command does not specify a timeout, it does not change $TEST.

    Return to top

    READ fixed-length

    READ specifying a maximum length reads (for example, READ X#10 for ten characters) until either the PIPE has supplied the specified number of characters, or a terminating delimiter. A fixed-length READ may include a timeout.

    Return to top

    WRITE Command

    The PIPE device does non-blocking writes. If a process tries to WRITE to a full PIPE and the WRITE would block the device implicitly tries to complete the operation up to10 times. If the implicit retries don't succeed (remain blocked), the WRITE sets $DEVICE to "1,Resource temporarily unavailable", $ZA to 9, and triggers an error. If the GT.M process has defined an EXCEPTION, $ETRAP or $ZTRAP, it may choose to retry the WRITE after some action or delay might remove data from the pipe.

    Return to top

    WRITE /EOF

    WRITE /EOF to a PIPE closes the underlying UNIX pipe to force the created process to flush data but does not CLOSE the PIPE device. When the GT.M process finishes READs from the PIPE device, it still should explicitly CLOSE the PIPE device. When the PIPE device's created process (“tr”, for example) buffers output written to a UNIX pipe, the GT.M process must do WRITE/EOF after its final WRITE to the PIPE device. To avoid an indefinite hang, the GT.M process must READ with timeout (typically 0) for any READs on the device prior to the WRITE /EOF. After the GT.M process does a WRITE /EOF on the PIPE device closing stdin and presenting EOF to the created process, forcing the created process to flush any buffered data to the UNIX pipe acting as input to the PIPE device, it no longer has to use timed READ, although it may.

    Return to top

    CLOSE Command

    The CLOSE of a PIPE device prevents all subsequent access to the pipes associated with the device. Unless the OPEN that created the device specified INDEPENDENT, the process terminates. Note that any subsequent attempt by the created process to read from its stdin (which would be a closed pipe) returns an EOF and typical UNIX behavior would be to terminate on such an event.

    Return to top

    PIPE Device Examples

    The following examples show the use of deviceparameters and status variables with PIPE devices.

    Example : 

                 SET p1="test1" 
             OPEN p1:(shell="/bin/sh":comm="cat")::"PIPE"
diff --git a/articles/gtmji-demo.html b/articles/gtmji-demo.html
deleted file mode 100644
index fb4d7ad..0000000
Binary files a/articles/gtmji-demo.html and /dev/null differ
diff --git a/articles/images/PIPE_IO_1.html b/articles/images/PIPE_IO_1.html
deleted file mode 100644
index c94a70a..0000000
Binary files a/articles/images/PIPE_IO_1.html and /dev/null differ
diff --git a/articles/images/PIPE_IO_2.html b/articles/images/PIPE_IO_2.html
deleted file mode 100644
index ca88dc5..0000000
Binary files a/articles/images/PIPE_IO_2.html and /dev/null differ
diff --git a/articles/images/PIPE_IO_3.html b/articles/images/PIPE_IO_3.html
deleted file mode 100644
index 4b96aef..0000000
Binary files a/articles/images/PIPE_IO_3.html and /dev/null differ
diff --git a/articles/images/PIPE_IO_4.html b/articles/images/PIPE_IO_4.html
deleted file mode 100644
index 2884789..0000000
Binary files a/articles/images/PIPE_IO_4.html and /dev/null differ
diff --git a/articles/images/V52000b.html b/articles/images/V52000b.html
deleted file mode 100644
index aa25c83..0000000
Binary files a/articles/images/V52000b.html and /dev/null differ
diff --git a/articles/images/V53001A.html b/articles/images/V53001A.html
deleted file mode 100644
index 79c48f9..0000000
Binary files a/articles/images/V53001A.html and /dev/null differ
diff --git a/articles/images/V54002a.html b/articles/images/V54002a.html
deleted file mode 100644
index b5ea9de..0000000
Binary files a/articles/images/V54002a.html and /dev/null differ
diff --git a/articles/images/V63-000A.html b/articles/images/V63-000A.html
deleted file mode 100644
index 9e63d08..0000000
Binary files a/articles/images/V63-000A.html and /dev/null differ
diff --git a/articles/images/V63-001.html b/articles/images/V63-001.html
deleted file mode 100644
index f1006c0..0000000
Binary files a/articles/images/V63-001.html and /dev/null differ
diff --git a/articles/images/V63-003A.html b/articles/images/V63-003A.html
deleted file mode 100644
index 5c2e0bf..0000000
Binary files a/articles/images/V63-003A.html and /dev/null differ
diff --git a/articles/images/caution.html b/articles/images/caution.html
deleted file mode 100644
index dc2099d..0000000
Binary files a/articles/images/caution.html and /dev/null differ
diff --git a/articles/images/dhpr4zmp_26dcc6vhf4_b.html b/articles/images/dhpr4zmp_26dcc6vhf4_b.html
deleted file mode 100644
index 07c5ce3..0000000
Binary files a/articles/images/dhpr4zmp_26dcc6vhf4_b.html and /dev/null differ
diff --git a/articles/images/dhpr4zmp_31wmqvh9f8_b.html b/articles/images/dhpr4zmp_31wmqvh9f8_b.html
deleted file mode 100644
index 4f5ffb6..0000000
Binary files a/articles/images/dhpr4zmp_31wmqvh9f8_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_116dctrqc96_b.html b/articles/images/dpqq6h6_116dctrqc96_b.html
deleted file mode 100644
index cd6c792..0000000
Binary files a/articles/images/dpqq6h6_116dctrqc96_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_121djvxq8t5_b.html b/articles/images/dpqq6h6_121djvxq8t5_b.html
deleted file mode 100644
index 13fc561..0000000
Binary files a/articles/images/dpqq6h6_121djvxq8t5_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_127drtnzgdx_b.html b/articles/images/dpqq6h6_127drtnzgdx_b.html
deleted file mode 100644
index b89a723..0000000
Binary files a/articles/images/dpqq6h6_127drtnzgdx_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_146f2ddzchr_b.html b/articles/images/dpqq6h6_146f2ddzchr_b.html
deleted file mode 100644
index 287b478..0000000
Binary files a/articles/images/dpqq6h6_146f2ddzchr_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_148hhnmhghj_b.html b/articles/images/dpqq6h6_148hhnmhghj_b.html
deleted file mode 100644
index 15ebc7d..0000000
Binary files a/articles/images/dpqq6h6_148hhnmhghj_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_149ghpb4rff_b.html b/articles/images/dpqq6h6_149ghpb4rff_b.html
deleted file mode 100644
index 71c4ed6..0000000
Binary files a/articles/images/dpqq6h6_149ghpb4rff_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_155cs8vtfd4_b.html b/articles/images/dpqq6h6_155cs8vtfd4_b.html
deleted file mode 100644
index 6ace12f..0000000
Binary files a/articles/images/dpqq6h6_155cs8vtfd4_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_157hfmf6mgg_b.html b/articles/images/dpqq6h6_157hfmf6mgg_b.html
deleted file mode 100644
index 2b98b9c..0000000
Binary files a/articles/images/dpqq6h6_157hfmf6mgg_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_158fq7xrpdd_b.html b/articles/images/dpqq6h6_158fq7xrpdd_b.html
deleted file mode 100644
index ccf3b33..0000000
Binary files a/articles/images/dpqq6h6_158fq7xrpdd_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_162dqb8nrc9_b.html b/articles/images/dpqq6h6_162dqb8nrc9_b.html
deleted file mode 100644
index fb33126..0000000
Binary files a/articles/images/dpqq6h6_162dqb8nrc9_b.html and /dev/null differ
diff --git a/articles/images/dpqq6h6_58srvjvdfg_b.html b/articles/images/dpqq6h6_58srvjvdfg_b.html
deleted file mode 100644
index b64e3e1..0000000
Binary files a/articles/images/dpqq6h6_58srvjvdfg_b.html and /dev/null differ
diff --git a/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html b/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html
deleted file mode 100644
index 78ccf80..0000000
Binary files a/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html and /dev/null differ
diff --git a/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html b/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html
deleted file mode 100644
index 88a92a5..0000000
Binary files a/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html and /dev/null differ
diff --git a/articles/images/important.html b/articles/images/important.html
deleted file mode 100644
index bf7d899..0000000
Binary files a/articles/images/important.html and /dev/null differ
diff --git a/articles/images/tip.html b/articles/images/tip.html
deleted file mode 100644
index 0ee18f4..0000000
Binary files a/articles/images/tip.html and /dev/null differ
diff --git a/articles/images/warning.html b/articles/images/warning.html
deleted file mode 100644
index ac44680..0000000
Binary files a/articles/images/warning.html and /dev/null differ
diff --git a/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html b/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html
new file mode 100644
index 0000000..df18d6a
Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html differ
diff --git a/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html b/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html
new file mode 100644
index 0000000..6378094
Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html differ
diff --git a/books/ao/OpenVMS_manual/ch07s02.html b/books/ao/OpenVMS_manual/ch07s02.html
index 753a8e9..59bdcd7 100644
--- a/books/ao/OpenVMS_manual/ch07s02.html
+++ b/books/ao/OpenVMS_manual/ch07s02.html
@@ -34,7 +34,7 @@ process.
  • Additional requirements for application
 the "Messaging" section which follows. As previously noted, all
 processes accessing a replicated database must use the same Global
 Directory. Do not use M extended references since they can have
-unpredictable results.

    • Figure 7.2. Logical Dual-Site Application Architecture

    Represents logical dual-site application architecture.

    Messaging

    For online operations, application servers on the primary respond to +unpredictable results.

    Figure 7.2. Logical Dual-Site Application Architecture

    Represents logical dual-site application architecture.

    Messaging

    For online operations, application servers on the primary respond to messages from clients delivered over a network. Each message is assumed to result in zero (inquiry) or one (updated) transaction on the server. The network that delivers messages must be robust. This means that each message @@ -371,7 +371,7 @@ up, it will act as the secondary and be forced to rollback all transactions performed while it was primary and Site A was down. These transactions become non-replicated transactions. If Site B came up first, then the non-replicated transactions would occur when Site A restarted. These would -be the transactions while A was primary after B failed.

    Figure 7.3. Complex Dual-Site Failure

    Represents Complex Dual-site Failure

    When recovering from these situations, the primary is always the current +be the transactions while A was primary after B failed.

    Figure 7.3. Complex Dual-Site Failure

    Represents Complex Dual-site Failure

    When recovering from these situations, the primary is always the current system of record when the secondary comes up. The secondary must roll its database back to the transaction with the highest journal sequence number for which both systems are known to be in agreement, and "catch up" from diff --git a/books/pg/OpenVMS_manual/examples_of_query.html b/books/pg/OpenVMS_manual/examples_of_query.html index eac07b2..6b5a430 100644 --- a/books/pg/OpenVMS_manual/examples_of_query.html +++ b/books/pg/OpenVMS_manual/examples_of_query.html @@ -46,7 +46,7 @@

    The tree diagram below represents the structure produced by the preceding routine.

    - +

    The following routine:

    diff --git a/books/pg/OpenVMS_manual/examples_of_ztcommit.html b/books/pg/OpenVMS_manual/examples_of_ztcommit.html
index f1f027a..cd389ed 100644
--- a/books/pg/OpenVMS_manual/examples_of_ztcommit.html
+++ b/books/pg/OpenVMS_manual/examples_of_ztcommit.html
@@ -42,7 +42,7 @@
       
    This ZTCOMMIT issued from Direct Mode would close any open ZTSTARTs.
    
       
    Example:
    
       
    
-    
+    
     
    
       
    This shows a transaction with two independent nested sub-transactions. For additional examples, refer to the ZTSTART examples.
    diff --git a/books/pg/OpenVMS_manual/pg_figures/ch6_001.html b/books/pg/OpenVMS_manual/pg_figures/ch6_001.html new file mode 100644 index 0000000..8e0e32c Binary files /dev/null and b/books/pg/OpenVMS_manual/pg_figures/ch6_001.html differ diff --git a/books/pg/OpenVMS_manual/pg_figures/ch7_001.html b/books/pg/OpenVMS_manual/pg_figures/ch7_001.html new file mode 100644 index 0000000..a02f092 Binary files /dev/null and b/books/pg/OpenVMS_manual/pg_figures/ch7_001.html differ