|
HP OpenVMS Systems Documentation |
|
The OpenVMS Frequently Asked Questions (FAQ)
Permit structure members to be naturally aligned whenever possible, and avoid using /NOMEMBER_ALIGNMENT. If you need to disable member alignment, use the equivilent #pragma to designate the specific structures. The alignment of structure members normally only comes into play with specific unaligned data structures---such as the sys$creprc quota itemlist---and with data structures that are using data that was organized by a system using byte or other non-member alignment. Versions of HP C such as V6.0 include the capability to extract the contents of the standard header libraries into directories such as SYS$SYSROOT:[DECC$LIB...], and provide various logical names that can be defined to control library searches. With HP C versions such as V6.0, the default operations of the compiler match the expectations of most OpenVMS programmers, without requiring any definitions of site-specific library-related logical names. (And logical names left from older DEC C versions can sometimes cause the compiler troubles locating header files.) HP C V5.6 and later include a backport library, a mechanism by which HP C running on older OpenVMS releases can gain access to newer RTL routines added to the RTL in later OpenVMS releases---the language RTLs ship with OpenVMS itself, and not with the compilers. Example C code is available in SYS$EXAMPLES:, in DECW$EXAMPLES (when the DECwindows examples are installed), in TCPIP$SERVICES (or on older releases, UCX$EXAMPLES) when HP TCP/IP Services is installed), on the Freeware CD-ROMs, and at web sites such as
For additional information on the OpenVMS Ask The Wizard (ATW) area and
for a pointer to the available ATW Wizard.zip archive, please see
Section 3.8.
The localtime() function and various other functions maintain the number of years since 1900 in the "struct tm" structure member tm_year. This field will contain a value of 100 in the year 2000, 101 for 2001, etc., and the yearly incrementation of this field is expected to continue. The C epoch typically uses a longword (known as time_t) to contain the number of seconds since midnight on 1-Jan-1970. At the current rate of consumption of seconds, this longword is expected to overflow (when interpreted as a signed longword) circa 03:14:07 on 19-Jan-2038 (GMT), as this time is circa 0x7FFFFFFF seconds since the C base date. (The most common solution is to ensure that time_t is an unsigned.) If C does not correctly handle the display of the local system time, then check the UTC configuration on OpenVMS---the most common symptom of this is a skew of one hour (or whatever the local daylight saving time change might be). This skew can be caused by incorrect handling of the "is_dst" setting in the application program, or by an incorrect OpenVMS UTC configuration on the local system. (See section Section 4.4.) Floating point is prohibited in OpenVMS Alpha inner-mode (privileged) code, and in any process or other execution context that does not have floating point enabled. C programmers developing and working with OpenVMS Alpha high-IPL kernel-mode code such as device drivers will want to become familiar with the floating point processing available in the environment, and with the C compiler qualifier /INSTRUCTION_SET=[NO]FLOATING_POINT. Device drivers and other similar kernel-mode C code must be compiled with /INSTRUCTION_SET=FLOATING_POINT and /EXTERN_MODEL=STRICT_REFDEF. Additionally, the SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY parameter will be needed to be appended to the module specification or declared via the C compiler's include library logical name mechanism when the C compiler is resolving kernel-mode data structures and definitions. This library contains OpenVMS kernel-mode and other system declaractions, and particularly a mixture of undocumented definitions and declarations, and particularly definitions and declarations that are subject to change (and that can accordingly lead to requirements for the recompilation of application code). In addition to the user-mode C Run-Time Library (RTL) mentioned in the OpenVMS C RTL documentation and referenced over in Section 3.9, there is a second and parallel kernel-mode RTL accessable to device drivers and other kernel code on OpenVMS Alpha and OpenVMS I64. The most common time this second C library is noticed is when C code is (erroneously) linked with /SYSEXE/SYSLIB, and duplicate symbol errors typically then arise. As code running in supervisor-, executive- or kernel-mode context cannot call out a user-mode RTL or other user-mode library, you will want to respecify the command as LINK /SYSEXE/NOSYSLIB. This will eliminate the duplicate symbol errors, since only the kernel-mode library will be referenced, and it will also avoid calling out into the user-mode libraries. When sharing variables with other languages, here is some example HP C code...
and here is some associated example Bliss code...
10.22.2 Other common C++ issuesHP C++ (a separate compiler from HP C) provides both symbol mangling and symbol decoration. Some of the details of working with longer symbol names and the resulting symbol name mangling in mixed language environments are listed in the shareable image cookbook, and in the C++ documentation. Symbol name decoration permits the overloading of functions (by adding characters to the external symbol for the function to indicate the function return type and the argument data types involved), and mixed-language external references can and often do need to disable this decoration via the extern "C" declaration mechanism:
Also see Section 14.7 for information on /ARCHITECTURE and /OPTIMIZE=TUNE. See Section 10.15 for information on the C system and the lib$spawn call in CAPTIVE environments. Constructs such as the order of incrementation or decrementation and the order of argument processing within an argument list are all implementation-defined. This means that C coding constructs such as:
are undefined and can have (adverse) implications when porting the C code to another C compiler or to another platform. In general, any combination of ++, --, =, +=, -=, *=, etc operators that will cause the same value to be modified multiple times (between what the ANSI/ISO C standard calls "sequence points") produce undefined and implementation-specific results. Within C, the following are the "sequence points": the ";" at the end of a C statment, the ||, &&, ?:, and comma operators, and a call to a function. Note specifically that = is NOT a sequence point, and that the individual arguments contained within a function argument list can be processed from right to left, from left to right, or at any random whim. HP C for OpenVMS VAX (formerly DEC C) and VAX C do differ in the related processing. So you are looking for OpenVMS-specific definitions (include files)? UCBDEF.H, PCBDEF.H and other OpenVMS-specific definitions---these are considered part of OpenVMS and not part of the C compiler kit---are available on all recent OpenVMS Alpha releases. To reference the version-dependent symbol library sys$share:sys$lib_c.tlb, use a command similar to the following for compilation:
You can also define DECC$TEXT_LIBRARY to reference the library. You will want to review the Programming Concepts manual, and specifically take a quick look at Chapter 21. And some general background: the STARLET definitions (and thus the sys$starlet_c.tlb library) contain the symbols and the definitions that are independent of the OpenVMS version. The LIB definitions (and thus sys$lib_c) contain symbols and definitions that can be dependent on the OpenVMS version. You won't need to rebuild your code after an OpenVMS upgrade if you have included definitions from STARLET. The same cannot be said for some of the definitions in LIB---you might need to rebuild your code. (The UCB structure can and has changed from release to release, for instance.) Recent versions of C automatically search sys$starlet_c.tlb. Explicit specification of sys$lib_c.tlb is required. Also see the Ask The Wizard website topics (2486), (3803), and (1661): For additional information on the OpenVMS Ask The Wizard (ATW) area and for a pointer to the available ATW Wizard.zip archive, please see Section 3.8.
See Section 9.5 for information on the C off_t limitations, resolved
in OpenVMS V7.3-1 and later and in ECO kits available for specific
OpenVMS releases. The use of a longword for off_t restricts
applications using native C I/O to file sizes of two gigabytes or less,
or these applications must use native RMS or XQP calls for specific
operations.
DECthreads V7.3 and the HP C compiler (also known as Compaq C and DEC C) V6.4 are presently expected to be the last updates and the last releases of these development packages for use on OpenVMS VAX. The run-time support for both DECthreads (CMA$RTL) and for C (DECC$CRTL) will continue to be maintained, and will continue to be available on OpenVMS VAX. The VAX C V3.2 compiler is the final VAX C compiler release for OpenVMS VAX, and the VAX C Run-Time Library (VAXCRTL) will also continue to be available.
New development and new features and product enhancements continue for
the OpenVMS Alpha and the OpenVMS IA-64 DECthreads and C compilers.
One of the common rules-of-thumb used for choosing a displayed version number string for a new version of a layered product or an application, its implications, and its expected effects on client applications and users, follows:
For additional version-numbering materials and for information on assigning module generation numbers, please see the OpenVMS (POLYCENTER) Software Product Installation Utility---variously refered to by acronyms including PCSI and SPIA---reference manual available within the OpenVMS documentation set. Of course, all of this is obviously subject to interpretation, particularly around the distinction between large and small changes and such. The scale of the application is also a factor, as larger and more complex applications will tend toward smaller increments and will tend to see the maintenance number incremented, while new releases of smaller applications will tend to see the minor version incremented somewhat more frequently.
The goal of all this is to provide a guide to relative scale of changes
and the associated effort involved in an upgrade for the user and/or
for the application programmer.
You can customize the device and directory for the process dump by defining the logical names SYS$PROCDMP and SYS$PROTECTED_PROCDMP. The former is for non-privileged dumps, while the latter is the location where privileged image dumps are written, and preferably an area protected against untrusted access. For example:
The abouve presumes that the SYS$ERRORLOG logical name points to a valid location.
There is presently no means to change the name of the generated dump
file from IMAGENAME.DMP to something else. Accordingly, you
will want to use different target directories for this purpose,
particularly if there is more than one application or process
potentially writing process dumps.
If you are interested in accessing the native Intel Itanium assembler within the OpenVMS I64 GNV environment---and since the iasi64 assembler is a Unix program and GNV is a Unix environment for OpenVMS I64---you can simply copy iasi64.ext into your gnu:[bin] directory in place of "as.", and of "AS.EXE". Alternately and probably also better, you can write an "as." script to invoke the iasi64.exe image from its particular prefered location on the local system. A typical "as." script looks like this:
10.27 Kernel-mode coding restrictions?Floating point is prohibited in OpenVMS Alpha inner-mode (privileged) code, and within any process or other execution context that does not have floating point enabled and available. Programmers developing and working with OpenVMS Alpha high-IPL kernel-mode code, such as device drivers, will further want to become familiar with the floating-point processing and the instruction set emulation available in the particular target environment (if any). When working with C, inner-mode programmers will want to become familiar with the C compiler qualifier /INSTRUCTION_SET=[NO]FLOATING_POINT. Device drivers and other similar kernel-mode C code must be compiled with /INSTRUCTION_SET=FLOATING_POINT and /EXTERN_MODEL=STRICT_REFDEF. Additionally, inner-mode code cannot call out to the user-mode language run-time libraries nor to any of the OpenVMS system run-time libraries. In particular, this prohibition prevents pages of inner-mode-protected memory from being allocated and interspersed within the user-mode heap or other such user-mode data structures. The prohibtion on user libraries also generally means that such code must be linked with LINK /NOSYSLIB, and quite probably also with /SYSEXE. The former causes the linker to avoid searching the system shareable image libraries (via IMAGELIB.OLB), while the latter brings in symbols typically only known to or otherwise accessable from the OpenVMS executuve. To include kernel-mode C programming definitions, macros and system constants within a C compilation, include SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY on the C compilation. (Constructs defined within the system macro library LIB.MLB or within its C equivalent SYS$LIB_C.TLB tend to be version-dependent, or undocumented, or both.) As an example of the compilation, the following is a typical C device driver compilation command:
Additionally, code running in executive mode in an AST or in kernel mode cannot call RMS services, or routines which directly or indirectly call RMS.
For related kernel-mode programming materials and driver documentation,
please see the Writing OpenVMS Alpha Device Driversin C book,
ISBN 1-55558-133-1.
To decode the virtual addresses returned by an access violation or by another similar OpenVMS display, you need to have created and retained a listings file---preferably one with machine code generation enabled---and a full link map. Starting with the virtual address reported by the error, use the link map to find the module that contributed the code that contains the virtual address range. Calculate the offset from the base of the range, by subtracting the base of the range from teh failing virtual address. Then use the compiler listings for the particular component that contributed the code to locate the offset of the failing instruction. If the map and listings information was not maintained, working backwards is far more difficult---you are left to use the binary instruction data around the failure to locate the associated source code, and this process is far more involved. This usually involves matching up blocks of decoded instructions around the failing code, or the direct analog involving matching up ranges of decoded instructions. Keep the maps and listing files around, in other words. Rather easier than an approach based on virtual address arithmetic and far easier than working backwards from the instruction stream is to use integrated debugging---this inclusion is arguably an essential component of any non-trivial application---and to use the OpenVMS Debugger. The OpenVMS Debugger in particular can be used to examine the source code, to examine the stack, and can even be programmed to wait patiently for the incidence of a particular value or failure or condition, and this is far easier than working backwards from the instruction stream is to use integrated debugging---this inclusion is arguably an essential component of any non-trivial application---and to use the OpenVMS Debugger. The debugger can also be activated from within a signal handler, and commands to generate a traceback can be generated directly, or through the invocation of a procedure containing a series of debugger commands.
Details on the debugger are in the OpenVMS Debugger Manual, and also
see the discussion of dyanmically activating the Debugger in
Section 10.19.
The following code can be used to generate an AUTODIN-II 32-bit Cyclic Redundency Check (CRC32) value from an input string descriptor, similar to that used by the HP C compiler for its /NAMES=SHORTENED mechanism, and by various other applications requiring a CRC32. The routine uses the OpenVMS library routine lib$crc_table to generate a sixteen longword array of data from the specified encoded polynomial coefficient (AUTODIN-II, in this case), and then lib$crc to generate the CRC32 value from the array and the input data.
10.30 Enabling built-in tracing?
To stop it from loading early in boot
The first occurance of the name TR$DEBUG within the command is considered the "product" and the second is considered the "image" that should exist within SYS$LOADABLE_IMAGES. When TR$DEBUG loads in the init phase, it will automatically turn on tracing. Also see the SDA TR extension.
|