gcc/doc/vms.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node VMS
   7 @chapter Using GCC on VMS
   8
   9 @c prevent bad page break with this line
  10 Here is how to use GCC on VMS@.
  11
  12 @menu
  13 * Global Declarations::    How to do globaldef, globalref and globalvalue with
  14                            GCC.
  15 * VMS Misc::               Misc information.
  16 @end menu
  17
  18 @node Global Declarations
  19 @section Global Declarations and VMS
  20
  21 @findex GLOBALREF
  22 @findex GLOBALDEF
  23 @findex GLOBALVALUEDEF
  24 @findex GLOBALVALUEREF
  25 GCC does not provide the @code{globalref}, @code{globaldef} and
  26 @code{globalvalue} keywords of VAX-C@.  You can get the same effect with
  27 an obscure feature of GAS, the GNU assembler.  (This requires GAS
  28 version 1.39 or later.)  The following macros allow you to use this
  29 feature in a fairly natural way:
  30
  31 @smallexample
  32 #ifdef __GNUC__
  33 #define GLOBALREF(TYPE,NAME)                      \
  34   TYPE NAME                                       \
  35   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME)
  36 #define GLOBALDEF(TYPE,NAME,VALUE)                \
  37   TYPE NAME                                       \
  38   asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \
  39     = VALUE
  40 #define GLOBALVALUEREF(TYPE,NAME)                 \
  41   const TYPE NAME[1]                              \
  42   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)
  43 #define GLOBALVALUEDEF(TYPE,NAME,VALUE)           \
  44   const TYPE NAME[1]                              \
  45   asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME)  \
  46     = @{VALUE@}
  47 #else
  48 #define GLOBALREF(TYPE,NAME) \
  49   globalref TYPE NAME
  50 #define GLOBALDEF(TYPE,NAME,VALUE) \
  51   globaldef TYPE NAME = VALUE
  52 #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \
  53   globalvalue TYPE NAME = VALUE
  54 #define GLOBALVALUEREF(TYPE,NAME) \
  55   globalvalue TYPE NAME
  56 #endif
  57 @end smallexample
  58
  59 @noindent
  60 (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the
  61 name is removed by the assembler, after it has modified the attributes
  62 of the symbol).  These macros are provided in the VMS binaries
  63 distribution in a header file @file{GNU_HACKS.H}.  An example of the
  64 usage is:
  65
  66 @example
  67 GLOBALREF (int, ijk);
  68 GLOBALDEF (int, jkl, 0);
  69 @end example
  70
  71 The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used
  72 straightforwardly for arrays, since there is no way to insert the array
  73 dimension into the declaration at the right place.  However, you can
  74 declare an array with these macros if you first define a typedef for the
  75 array type, like this:
  76
  77 @example
  78 typedef int intvector[10];
  79 GLOBALREF (intvector, foo);
  80 @end example
  81
  82 Array and structure initializers will also break the macros; you can
  83 define the initializer to be a macro of its own, or you can expand the
  84 @code{GLOBALDEF} macro by hand.  You may find a case where you wish to
  85 use the @code{GLOBALDEF} macro with a large array, but you are not
  86 interested in explicitly initializing each element of the array.  In
  87 such cases you can use an initializer like: @code{@{0,@}}, which will
  88 initialize the entire array to @code{0}.
  89
  90 A shortcoming of this implementation is that a variable declared with
  91 @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array.  For
  92 example, the declaration:
  93
  94 @example
  95 GLOBALVALUEREF(int, ijk);
  96 @end example
  97
  98 @noindent
  99 declares the variable @code{ijk} as an array of type @code{int [1]}.
 100 This is done because a globalvalue is actually a constant; its ``value''
 101 is what the linker would normally consider an address.  That is not how
 102 an integer value works in C, but it is how an array works.  So treating
 103 the symbol as an array name gives consistent results---with the
 104 exception that the value seems to have the wrong type.  @strong{Don't
 105 try to access an element of the array.}  It doesn't have any elements.
 106 The array ``address'' may not be the address of actual storage.
 107
 108 The fact that the symbol is an array may lead to warnings where the
 109 variable is used.  Insert type casts to avoid the warnings.  Here is an
 110 example; it takes advantage of the ISO C feature allowing macros that
 111 expand to use the same name as the macro itself.
 112
 113 @example
 114 GLOBALVALUEREF (int, ss$_normal);
 115 GLOBALVALUEDEF (int, xyzzy,123);
 116 #ifdef __GNUC__
 117 #define ss$_normal ((int) ss$_normal)
 118 #define xyzzy ((int) xyzzy)
 119 #endif
 120 @end example
 121
 122 Don't use @code{globaldef} or @code{globalref} with a variable whose
 123 type is an enumeration type; this is not implemented.  Instead, make the
 124 variable an integer, and use a @code{globalvaluedef} for each of the
 125 enumeration values.  An example of this would be:
 126
 127 @example
 128 #ifdef __GNUC__
 129 GLOBALDEF (int, color, 0);
 130 GLOBALVALUEDEF (int, RED, 0);
 131 GLOBALVALUEDEF (int, BLUE, 1);
 132 GLOBALVALUEDEF (int, GREEN, 3);
 133 #else
 134 enum globaldef color @{RED, BLUE, GREEN = 3@};
 135 #endif
 136 @end example
 137
 138 @node VMS Misc
 139 @section Other VMS Issues
 140
 141 @cindex exit status and VMS
 142 @cindex return value of @code{main}
 143 @cindex @code{main} and the exit status
 144 GCC automatically arranges for @code{main} to return 1 by default if
 145 you fail to specify an explicit return value.  This will be interpreted
 146 by VMS as a status code indicating a normal successful completion.
 147 Version 1 of GCC did not provide this default.
 148
 149 GCC on VMS works only with the GNU assembler, GAS@.  You need version
 150 1.37 or later of GAS in order to produce value debugging information for
 151 the VMS debugger.  Use the ordinary VMS linker with the object files
 152 produced by GAS@.
 153
 154 @cindex shared VMS run time system
 155 @cindex @file{VAXCRTL}
 156 Under previous versions of GCC, the generated code would occasionally
 157 give strange results when linked to the sharable @file{VAXCRTL} library.
 158 Now this should work.
 159
 160 A caveat for use of @code{const} global variables: the @code{const}
 161 modifier must be specified in every external declaration of the variable
 162 in all of the source files that use that variable.  Otherwise the linker
 163 will issue warnings about conflicting attributes for the variable.  Your
 164 program will still work despite the warnings, but the variable will be
 165 placed in writable storage.
 166
 167 @cindex name augmentation
 168 @cindex case sensitivity and VMS
 169 @cindex VMS and case sensitivity
 170 Although the VMS linker does distinguish between upper and lower case
 171 letters in global symbols, most VMS compilers convert all such symbols
 172 into upper case and most run-time library routines also have upper case
 173 names.  To be able to reliably call such routines, GCC (by means of
 174 the assembler GAS) converts global symbols into upper case like other
 175 VMS compilers.  However, since the usual practice in C is to distinguish
 176 case, GCC (via GAS) tries to preserve usual C behavior by augmenting
 177 each name that is not all lower case.  This means truncating the name
 178 to at most 23 characters and then adding more characters at the end
 179 which encode the case pattern of those 23.   Names which contain at
 180 least one dollar sign are an exception; they are converted directly into
 181 upper case without augmentation.
 182
 183 Name augmentation yields bad results for programs that use precompiled
 184 libraries (such as Xlib) which were generated by another compiler.  You
 185 can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation;
 186 it makes external C functions and variables case-independent as is usual
 187 on VMS@.  Alternatively, you could write all references to the functions
 188 and variables in such libraries using lower case; this will work on VMS,
 189 but is not portable to other systems.  The compiler option @samp{/NAMES}
 190 also provides control over global name handling.
 191
 192 Function and variable names are handled somewhat differently with G++.
 193 The GNU C++ compiler performs @dfn{name mangling} on function
 194 names, which means that it adds information to the function name to
 195 describe the data types of the arguments that the function takes.  One
 196 result of this is that the name of a function can become very long.
 197 Since the VMS linker only recognizes the first 31 characters in a name,
 198 special action is taken to ensure that each function and variable has a
 199 unique name that can be represented in 31 characters.
 200
 201 If the name (plus a name augmentation, if required) is less than 32
 202 characters in length, then no special action is performed.  If the name
 203 is longer than 31 characters, the assembler (GAS) will generate a
 204 hash string based upon the function name, truncate the function name to
 205 23 characters, and append the hash string to the truncated name.  If the
 206 @samp{/VERBOSE} compiler option is used, the assembler will print both
 207 the full and truncated names of each symbol that is truncated.
 208
 209 The @samp{/NOCASE_HACK} compiler option should not be used when you are
 210 compiling programs that use libg++.  libg++ has several instances of
 211 objects (i.e.  @code{Filebuf} and @code{filebuf}) which become
 212 indistinguishable in a case-insensitive environment.  This leads to
 213 cases where you need to inhibit augmentation selectively (if you were
 214 using libg++ and Xlib in the same program, for example).  There is no
 215 special feature for doing this, but you can get the result by defining a
 216 macro for each mixed case symbol for which you wish to inhibit
 217 augmentation.  The macro should expand into the lower case equivalent of
 218 itself.  For example:
 219
 220 @example
 221 #define StuDlyCapS studlycaps
 222 @end example
 223
 224 These macro definitions can be placed in a header file to minimize the
 225 number of changes to your source code.