documentation

gcc/cobol/gcobol.1

@@ -175,13 +175,17 @@ With
 .Fl fno-static-call ,
 .Nm
 never uses static linking for 
-.D1 Sy CALL Ar program Ns .
+.D1 Sy CALL Ar program
 By default, or with
 .Fl fstatic-call ,
+if
+.Ar program
+is an alphanumeric literal,
 .Nm
-uses static linkage if
+uses static linkage, meaning the compiler produces an external symbol
 .Ar program
-is an alphanumeric literal.  (In the future, for
+for the linker to resolve.
+(In the future, that will work with
 .Sy CONSTANT
 data items, too.)  With static linkage, if
 .Ar program
@@ -287,6 +291,26 @@ At the present time, this is an all-or-nothing setting.  Support for
 and
 .Sy CODESET ,
 which would allow conversion between encodings, remains a future goal.  
+.Ss REDEFINES ... USAGE POINTER
+Per ISO, an item that
+.Sy REDEFINES
+another may not be larger than the item it redefines, unless that item
+has LEVEL 01 and is not EXTERNAL.  In
+.Nm ,
+using
+.Fl dialect Ar ibm ,
+this rule is relaxed for
+.Sy REDEFINES
+with
+.Sy USAGE POINTER
+whose redefined member is a 4-byte
+.Sy USAGE COMP-5
+(usually
+.Sy PIC S9(8) Ns ).
+In that case, the redefined member is re-sized to be 8 bytes, to
+accommodate the pointer.  This feature allows pointer arithmetic on a
+64-bit system with source code targeted at a 32-bit system.
+.Sy
 .
 .Sh IMPLEMENTATION NOTES
 .Nm
@@ -297,20 +321,22 @@ specification, any such conflicts are resolved in favor of gcc.
 .Ss Linking
 Unlike, C, the \*[lang]
 .Sy CALL
-statement implies dynamic linking, because the
-.Sy CALL
-parameter can be a variable whose value is determined at runtime.
+statement implies dynamic linking, because for
+.D1 Sy CALL Ar program
+.Ar program
+can be a variable whose value is determined at runtime.
 However, the parameter may also be compile-time constant, either an
 alphanumeric literal, or a
 .Sy CONSTANT
 data item.
 .Pp
 .Nm
-supports static linking where possible.  If the parameter value is
-known at compile time, the compiler produces an external reference to
-be resolved by the linker.  The referenced program is normally supplied
-via an object module, a static library, or a shared object.  If it is
-not supplied, the linker will report an
+supports static linking where possible, unless defeated by
+.Fl no-static-call .
+If the parameter value is known at compile time, the compiler produces
+an external reference to be resolved by the linker.  The referenced
+program is normally supplied via an object module, a static library,
+or a shared object.  If it is not supplied, the linker will report an
 .Dq "unresolved symbol"
 error, either at build time or, if using a shared object, when the
 program is executed.  This feature informs the programmer of the error
@@ -320,6 +346,16 @@ Programs that are expected to execute
 correctly in the presence of an unresolved symbol (perhaps because the
 program logic won't require that particular
 .Sy CALL )
+can use the
+.Fl no-static-call
+option.  That forces all
+.Sy CALL
+statements to be resolved dynamically, at runtime. 
+.ig
+Programs that are expected to execute
+correctly in the presence of an unresolved symbol (perhaps because the
+program logic won't require that particular
+.Sy CALL )
 can use linker options to produce an executable anyway.  
 .Pp
 One corner case yet remains.  The
@@ -353,7 +389,8 @@ Should your program meet those particular conditions, all is not lost.
 There are workarounds, and an option could be added to use dynamic
 linking for all
 .Sy CALL
-statement, regardless of compile-time constants.  
+statement, regardless of compile-time constants.
+..
 .
 .Sh EXTENSIONS TO ISO \*[lang]
 Standard \*[lang] has no provision for environment variables as defined
@@ -691,7 +728,7 @@ statement, with or without its
 .Sy REPLACING
 component.  For any statement
 .sp
-.D1 "COPY copybook"
+.D1 COPY Ar copybook
 .sp
 .Nm
 looks first for an environment variable named