aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog6
-rw-r--r--doc/gawk.info124
-rw-r--r--doc/gawk.texi46
-rw-r--r--doc/gawktexi.in46
4 files changed, 163 insertions, 59 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 82150f34..8c58e5d4 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,9 +1,13 @@
+2013-12-23 John E. Malmberg <wb8tyw@qsl.net>
+
+ * gawktexi.in: Document the VMS exit status encoding.
+
2013-12-21 Arnold D. Robbins <arnold@skeeve.com>
* gawktexi.in (Additional Configuration Options): Document
the --disable-extensions option.
-2013-12-16 John E. Malmberg <wb8tyw@qsl.net>
+2013-12-16 John E. Malmberg <wb8tyw@qsl.net>
* gawktexi.in: Updates to VMS sections.
diff --git a/doc/gawk.info b/doc/gawk.info
index 2589f0b5..4b1352f7 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -26255,7 +26255,7 @@ B.3.2.1 Compiling `gawk' on VMS
To compile `gawk' under VMS, there is a `DCL' command procedure that
issues all the necessary `CC' and `LINK' commands. There is also a
-`Makefile' for use with the `MMS' or `MMK' utility. From the source
+`Makefile' for use with the `MMS' and `MMK' utilities. From the source
directory, use either:
$ @[.vms]vmsbuild.com
@@ -26268,8 +26268,8 @@ or:
$ MMK/DESCRIPTION=[.vms]descrip.mms gawk
- `MMK' is an open source freeware near clone of `MMS' and can better
-handle `ODS-5' volumes with upper- and lower-case filenames. `MMK' is
+ `MMK' is an open source, free, near-clone of `MMS' and can better
+handle `ODS-5' volumes with upper- and lowercase filenames. `MMK' is
available from `https://github.com/endlesssoftware/mmk'.
With `ODS-5' volumes and extended parsing enabled, the case of the
@@ -26301,10 +26301,11 @@ B.3.2.2 Compiling `gawk' Dynamic Extensions on VMS
..................................................
Dynamic extensions need to be compiled with the same compiler options
-for floating point, pointer size, and symbol name handling as `gawk'.
-Alpha and Itanium should use IEEE floating point. The pointer size is
-32 bits, and the symbol name handling is to be exact case with CRC
-shortening for symbols longer than 32 bits.
+for floating point, pointer size, and symbol name handling as were used
+to compile `gawk' itself. Alpha and Itanium should use IEEE floating
+point. The pointer size is 32 bits, and the symbol name handling
+should be exact case with CRC shortening for symbols longer than 32
+bits.
For Alpha and Itanium:
@@ -26404,6 +26405,35 @@ If any other dash-type options (or multiple parameters such as data
files to process) are present, there is no ambiguity and `--' can be
omitted.
+ The `exit' value is a Unix-style value and is encoded to a VMS exit
+status value when the program exits.
+
+ The VMS severity bits will be set based on the `exit' value. A
+failure is indicated by 1 and VMS sets the `ERROR' status. A fatal
+error is indicated by 2 and VMS will set the `FATAL' status. All other
+values will have the `SUCCESS' status. The exit value is encoded to
+comply with VMS coding standards and will have the `C_FACILITY_NO' of
+`0x350000' with the constant `0xA000' added to the number shifted over
+by 3 bits to make room for the severity codes.
+
+ To extract the actual `gawk' exit code from the VMS status use:
+
+ unix_status = (vms_status .and. &x7f8) / 8
+
+A C program that uses `exec()' to call `gawk' will get the original
+Unix-style exit value.
+
+ Older versions of `gawk' treated a Unix exit code 0 as 1, a failure
+as 2, a fatal error as 4, and passed all the other numbers through.
+This violated the VMS exit status coding requirements.
+
+ VAX/VMS floating point uses unbiased rounding. *Note Round
+Function::.
+
+ VMS reports time values in GMT unless one of the `SYS$TIMEZONE_RULE'
+or `TZ' logical names is set. Older versions of VMS, such as VAX/VMS
+7.3 do not set these logical names.
+
The default search path, when looking for `awk' program files
specified by the `-f' option, is `"SYS$DISK:[],AWK_LIBRARY:"'. The
logical name `AWKPATH' can be used to override this default. The format
@@ -26420,7 +26450,7 @@ B.3.2.5 The VMS GNV Project
The VMS GNV package provides a build environment similar to POSIX with
ports of a collection of open source tools. The `gawk' found in the GNV
base kit is an older port. Currently the GNV project is being
-reorganized to be individual PCSI packages for each component. See
+reorganized to supply individual PCSI packages for each component. See
`https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/'.
The normal build procedure for `gawk' produces a program that is
@@ -30577,6 +30607,7 @@ Index
* exclamation point (!), !~ operator: Regexp Usage. (line 19)
* exit statement: Exit Statement. (line 6)
* exit status, of gawk: Exit Status. (line 6)
+* exit status, of VMS: VMS Running. (line 29)
* exp() function: Numeric Functions. (line 18)
* expand utility: Very Simple. (line 69)
* Expat XML parser library: gawkextlib. (line 33)
@@ -30726,6 +30757,7 @@ Index
(line 6)
* floating-point, numbers <1>: Unexpected Results. (line 6)
* floating-point, numbers: General Arithmetic. (line 6)
+* floating-point, VAX/VMS: VMS Running. (line 51)
* fnmatch extension function: Extension Sample Fnmatch.
(line 6)
* FNR variable <1>: Auto-set. (line 103)
@@ -31805,13 +31837,13 @@ Index
* Schorr, Andrew: Acknowledgments. (line 60)
* Schreiber, Bert: Acknowledgments. (line 38)
* Schreiber, Rita: Acknowledgments. (line 38)
-* search paths <1>: VMS Running. (line 29)
+* search paths <1>: VMS Running. (line 58)
* search paths <2>: PC Using. (line 11)
* search paths <3>: Igawk Program. (line 368)
* search paths <4>: AWKLIBPATH Variable. (line 6)
* search paths: AWKPATH Variable. (line 6)
* search paths, for shared libraries: AWKLIBPATH Variable. (line 6)
-* search paths, for source files <1>: VMS Running. (line 29)
+* search paths, for source files <1>: VMS Running. (line 58)
* search paths, for source files <2>: PC Using. (line 11)
* search paths, for source files <3>: Igawk Program. (line 368)
* search paths, for source files: AWKPATH Variable. (line 6)
@@ -32748,41 +32780,41 @@ Node: VMS Installation1054207
Node: VMS Compilation1054971
Ref: VMS Compilation-Footnote-11056586
Node: VMS Dynamic Extensions1056644
-Node: VMS Installation Details1057665
-Node: VMS Running1059499
-Node: VMS GNV1061101
-Node: VMS Old Gawk1061806
-Node: Bugs1062276
-Node: Other Versions1066132
-Node: Notes1072216
-Node: Compatibility Mode1073016
-Node: Additions1073799
-Node: Accessing The Source1074726
-Node: Adding Code1076166
-Node: New Ports1082211
-Node: Derived Files1086346
-Ref: Derived Files-Footnote-11091667
-Ref: Derived Files-Footnote-21091701
-Ref: Derived Files-Footnote-31092301
-Node: Future Extensions1092399
-Node: Implementation Limitations1092976
-Node: Extension Design1094228
-Node: Old Extension Problems1095382
-Ref: Old Extension Problems-Footnote-11096890
-Node: Extension New Mechanism Goals1096947
-Ref: Extension New Mechanism Goals-Footnote-11100312
-Node: Extension Other Design Decisions1100498
-Node: Extension Future Growth1102604
-Node: Old Extension Mechanism1103440
-Node: Basic Concepts1105180
-Node: Basic High Level1105861
-Ref: figure-general-flow1106132
-Ref: figure-process-flow1106731
-Ref: Basic High Level-Footnote-11109960
-Node: Basic Data Typing1110145
-Node: Glossary1113500
-Node: Copying1138962
-Node: GNU Free Documentation License1176519
-Node: Index1201656
+Node: VMS Installation Details1057695
+Node: VMS Running1059529
+Node: VMS GNV1062363
+Node: VMS Old Gawk1063072
+Node: Bugs1063542
+Node: Other Versions1067398
+Node: Notes1073482
+Node: Compatibility Mode1074282
+Node: Additions1075065
+Node: Accessing The Source1075992
+Node: Adding Code1077432
+Node: New Ports1083477
+Node: Derived Files1087612
+Ref: Derived Files-Footnote-11092933
+Ref: Derived Files-Footnote-21092967
+Ref: Derived Files-Footnote-31093567
+Node: Future Extensions1093665
+Node: Implementation Limitations1094242
+Node: Extension Design1095494
+Node: Old Extension Problems1096648
+Ref: Old Extension Problems-Footnote-11098156
+Node: Extension New Mechanism Goals1098213
+Ref: Extension New Mechanism Goals-Footnote-11101578
+Node: Extension Other Design Decisions1101764
+Node: Extension Future Growth1103870
+Node: Old Extension Mechanism1104706
+Node: Basic Concepts1106446
+Node: Basic High Level1107127
+Ref: figure-general-flow1107398
+Ref: figure-process-flow1107997
+Ref: Basic High Level-Footnote-11111226
+Node: Basic Data Typing1111411
+Node: Glossary1114766
+Node: Copying1140228
+Node: GNU Free Documentation License1177785
+Node: Index1202922

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index b56fbbad..43e518c1 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -34863,7 +34863,7 @@ The older designation ``VMS'' is used throughout to refer to OpenVMS.
To compile @command{gawk} under VMS, there is a @code{DCL} command procedure
that issues all the necessary @code{CC} and @code{LINK} commands. There is
-also a @file{Makefile} for use with the @code{MMS} or @code{MMK} utility.
+also a @file{Makefile} for use with the @code{MMS} and @code{MMK} utilities.
From the source directory, use either:
@example
@@ -34884,8 +34884,8 @@ or:
$ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms gawk}
@end example
-@code{MMK} is an open source freeware near clone of @code{MMS} and
-can better handle @code{ODS-5} volumes with upper- and lower-case filenames.
+@code{MMK} is an open source, free, near-clone of @code{MMS} and
+can better handle @code{ODS-5} volumes with upper- and lowercase filenames.
@code{MMK} is available from @uref{https://github.com/endlesssoftware/mmk}.
With @code{ODS-5} volumes and extended parsing enabled, the case of the target
@@ -34911,9 +34911,10 @@ a PCSI kit for compatible with the GNV product.
@appendixsubsubsec Compiling @command{gawk} Dynamic Extensions on VMS
Dynamic extensions need to be compiled with the same compiler options for
-floating point, pointer size, and symbol name handling as @command{gawk}.
+floating point, pointer size, and symbol name handling as were used
+to compile @command{gawk} itself.
Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits,
-and the symbol name handling is to be exact case with CRC shortening for
+and the symbol name handling should be exact case with CRC shortening for
symbols longer than 32 bits.
For Alpha and Itanium:
@@ -35027,6 +35028,39 @@ flag is required to force Unix-style parsing rather than @code{DCL} parsing. If
other dash-type options (or multiple parameters such as data files to
process) are present, there is no ambiguity and @option{--} can be omitted.
+@cindex exit status, of VMS
+The @code{exit} value is a Unix-style value and is encoded to a VMS exit
+status value when the program exits.
+
+The VMS severity bits will be set based on the @code{exit} value.
+A failure is indicated by 1 and VMS sets the @code{ERROR} status.
+A fatal error is indicated by 2 and VMS will set the @code{FATAL} status.
+All other values will have the @code{SUCCESS} status. The exit value is
+encoded to comply with VMS coding standards and will have the
+@code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000}
+added to the number shifted over by 3 bits to make room for the severity codes.
+
+To extract the actual @command{gawk} exit code from the VMS status use:
+
+@example
+unix_status = (vms_status .and. &x7f8) / 8
+@end example
+
+@noindent
+A C program that uses @code{exec()} to call @command{gawk} will get the original
+Unix-style exit value.
+
+Older versions of @command{gawk} treated a Unix exit code 0 as 1, a failure
+as 2, a fatal error as 4, and passed all the other numbers through.
+This violated the VMS exit status coding requirements.
+
+@cindex floating-point, VAX/VMS
+VAX/VMS floating point uses unbiased rounding. @xref{Round Function}.
+
+VMS reports time values in GMT unless one of the @code{SYS$TIMEZONE_RULE}
+or @code{TZ} logical names is set. Older versions of VMS, such as VAX/VMS
+7.3 do not set these logical names.
+
@c @cindex directory search
@c @cindex path, search
@cindex search paths
@@ -35044,7 +35078,7 @@ translation and not a multitranslation @code{RMS} searchlist.
The VMS GNV package provides a build environment similar to POSIX with ports
of a collection of open source tools. The @command{gawk} found in the GNV
base kit is an older port. Currently the GNV project is being reorganized
-to be individual PCSI packages for each component.
+to supply individual PCSI packages for each component.
See @uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.
The normal build procedure for @command{gawk} produces a program that
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 51b90877..fc465648 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -34012,7 +34012,7 @@ The older designation ``VMS'' is used throughout to refer to OpenVMS.
To compile @command{gawk} under VMS, there is a @code{DCL} command procedure
that issues all the necessary @code{CC} and @code{LINK} commands. There is
-also a @file{Makefile} for use with the @code{MMS} or @code{MMK} utility.
+also a @file{Makefile} for use with the @code{MMS} and @code{MMK} utilities.
From the source directory, use either:
@example
@@ -34033,8 +34033,8 @@ or:
$ @kbd{MMK/DESCRIPTION=[.vms]descrip.mms gawk}
@end example
-@code{MMK} is an open source freeware near clone of @code{MMS} and
-can better handle @code{ODS-5} volumes with upper- and lower-case filenames.
+@code{MMK} is an open source, free, near-clone of @code{MMS} and
+can better handle @code{ODS-5} volumes with upper- and lowercase filenames.
@code{MMK} is available from @uref{https://github.com/endlesssoftware/mmk}.
With @code{ODS-5} volumes and extended parsing enabled, the case of the target
@@ -34060,9 +34060,10 @@ a PCSI kit for compatible with the GNV product.
@appendixsubsubsec Compiling @command{gawk} Dynamic Extensions on VMS
Dynamic extensions need to be compiled with the same compiler options for
-floating point, pointer size, and symbol name handling as @command{gawk}.
+floating point, pointer size, and symbol name handling as were used
+to compile @command{gawk} itself.
Alpha and Itanium should use IEEE floating point. The pointer size is 32 bits,
-and the symbol name handling is to be exact case with CRC shortening for
+and the symbol name handling should be exact case with CRC shortening for
symbols longer than 32 bits.
For Alpha and Itanium:
@@ -34176,6 +34177,39 @@ flag is required to force Unix-style parsing rather than @code{DCL} parsing. If
other dash-type options (or multiple parameters such as data files to
process) are present, there is no ambiguity and @option{--} can be omitted.
+@cindex exit status, of VMS
+The @code{exit} value is a Unix-style value and is encoded to a VMS exit
+status value when the program exits.
+
+The VMS severity bits will be set based on the @code{exit} value.
+A failure is indicated by 1 and VMS sets the @code{ERROR} status.
+A fatal error is indicated by 2 and VMS will set the @code{FATAL} status.
+All other values will have the @code{SUCCESS} status. The exit value is
+encoded to comply with VMS coding standards and will have the
+@code{C_FACILITY_NO} of @code{0x350000} with the constant @code{0xA000}
+added to the number shifted over by 3 bits to make room for the severity codes.
+
+To extract the actual @command{gawk} exit code from the VMS status use:
+
+@example
+unix_status = (vms_status .and. &x7f8) / 8
+@end example
+
+@noindent
+A C program that uses @code{exec()} to call @command{gawk} will get the original
+Unix-style exit value.
+
+Older versions of @command{gawk} treated a Unix exit code 0 as 1, a failure
+as 2, a fatal error as 4, and passed all the other numbers through.
+This violated the VMS exit status coding requirements.
+
+@cindex floating-point, VAX/VMS
+VAX/VMS floating point uses unbiased rounding. @xref{Round Function}.
+
+VMS reports time values in GMT unless one of the @code{SYS$TIMEZONE_RULE}
+or @code{TZ} logical names is set. Older versions of VMS, such as VAX/VMS
+7.3 do not set these logical names.
+
@c @cindex directory search
@c @cindex path, search
@cindex search paths
@@ -34193,7 +34227,7 @@ translation and not a multitranslation @code{RMS} searchlist.
The VMS GNV package provides a build environment similar to POSIX with ports
of a collection of open source tools. The @command{gawk} found in the GNV
base kit is an older port. Currently the GNV project is being reorganized
-to be individual PCSI packages for each component.
+to supply individual PCSI packages for each component.
See @uref{https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/}.
The normal build procedure for @command{gawk} produces a program that
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-05 19:59:22 +0000