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.

10.24 Choosing a Version Number for Application Code?

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:

• No functional and no application-visible changes, bugfixes only---the edit number is incremented. These tend to be very small, very isolated, or ECO-level changes. These can also be distributions for specific hardware configurations or platforms, as is the case with an OpenVMS Limited Hardware Release (LHR). Application rebuilds are not expected, and there is an assumption that general user-provided application-related regression testing will not be required.
• Minimal functional and very few user-visible changes---the maintenance number is incremented. These tend to be very small or even ECO-level changes, though somewhat larger than an edit-level change. Application rebuilds are not expected, and there is an assumption that user-provided application-related regression testing will not be required.
• Various small and upward-compatible functional changes---the minor version number is incremented. The changes are user-visible, and are intended to be user-visible. Application rebuilds are not expected. Some application programmers may choose to perform regression tests.
• Large and/or potentially incompatible changes---the major version number is incremented. Some applications might need to be rebuilt. Various application programmers will choose to perform regression tests of their respective applications.

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.

10.25 Selecting a Process Dump Directory?

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:

$ define SYS$PROCDMP SYS$ERRORLOG: $ define /exec SYS$PROTECTED_PROCDMP SYS$ERRORLOG:

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.

10.26 Access to Itanium Assembler?

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:

path/iasi64.exe $1 $2 $3 $4 $5

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:

$ CC /STANDARD=RELAXED_ANSI89/INSTRUCTION=NOFLOATING_POINT/EXTERN=STRICT - 'DEBUG_CC_DQ_OPT' 'ARCH_CC_OPT' 'CHECK_CC_OPT' 'SHOW_CC_OPT' - /LIS=LIS$:xxDRIVER/MACHINE_CODE/OBJ=OBJ$:xxDRIVER - SRC$:xxDRIVER.C+SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY

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.

10.28 Decoding an Access Violation (ACCVIO) Error?

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.

10.29 Generating an AUTODIN-II CRC32?

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.

static int CreateCRC32( struct dsc$descriptor *InputDataDesc ) { uint32 AUTODIN2; uint32 Seed = ~0UL; uint32 Coefficient = 0x0EDB88320UL; uint32 CRCArray[16]; lib$establish( lib$sig_to_ret ); lib$crc_table( (void *) &Coefficient, (void *) CRCArray ); AUTODIN2 = lib$crc( (void *) CRCArray, (void *) &Seed, InputDataDesc ); AUTODIN2 ^= Seed; return AUTODIN2; }

10.30 Enabling built-in tracing?

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> SYS_LOAD ADD TR$DEBUG TR$DEBUG/LOAD_STEP=INIT/LOG SYSMAN> Exit $ @SYS$UPDATE:VMS$SYSTEM_IMAGES.COM

To stop it from loading early in boot

$ RUN SYS$SYSTEM:SYSMAN SYSMAN> SYS_LOAD REMOVE TR$DEBUG TR$DEBUG/LOG SYSMAN> Exit $ @SYS$UPDATE:VMS$SYSTEM_IMAGES.COM

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.

For details of using these tracing mechanisms, see the tr_print macros in lib.mlb (Macro32), in sys$lib_c.tlb (C) and lib.req (Bliss) libraries.

10.31 Accessing a web server from DCL?

Programmatic access to the world-wide web is available from within DCL command procedures using available software packages including cURL, FETCH_HTTP, and Lynx, and there is the universal web client telnet. Using these packages, you can access a web server and can (within limits) process HTML from within a DCL command procedure.

For information and locations for these and of other packages, see Section 13.1.

DCL can also be used as a CGI script implementation language from within Apache and most (all?) other OpenVMS web servers. As a rule, perl and python and such will be more flexible and will have dedicated processing libraries available for common web and http-related tasks, but DCL can deal easily with many of the more typical tasks required of a CGI script. There are examples of DCL CGI scripts available, and most (all?) OpenVMS web server packages will include specific examples within the particular package or the package documentation.

If you are searching for something here, please consider using the text-format FAQ.

On a workstation, you will want to use the "Customize" menu of the session manager utility and select "Security". When the pop-up box appears, you can select the host node, username, and tranport that will allow you to launch an application that targets the workstation display.

If this does not provide you with access to the display, You need a checklist of sorts:

• Make sure that you've specified the X-windows "display" correctly on the remote host. For a DECnet transport, the specification uses two colons, while the TCP/IP transport typically uses one. The X Windows server and the X Windows screen follow the host specification, delimited by a period. For example:

  Table 11-1 X Windows Display Commands

  Shell	Command
  csh
  	# setenv DISPLAY vms.domain:0.0
  sh and ksh
  	# $ DISPLAY=vms.domain:0.0 ; export DISPLAY
  DCL
  	$ SET DISPLAY/CREATE/NODE=vms.domain - /TRANSPORT=TCPIP/SERVER=server/SCREEN=screen

• If you have verified the command is correct and things are still not working, ensure the Security settings on the OpenVMS host side will allow the incoming connection: Pull down the "Options" menu in the Session Manager, and select "Security...". If you do not find your host and username and transport listed among the authorized users, you will need to add an entry.
  • There are various transports available, including LOCAL, DECNET, LAT, and TCPIP. You must Select the transport appropriate to the incoming connection.
  • If the transport is "DECnet", do NOT add the double colon (::) to the node name.
  • If the transport is "TCPIP", "Username" must be an asterisk (*). Why? Because unlike DECnet, the TCP/IP protocol does not provide the remote username information in the incoming connection.
  • If the connection is "TCPIP", it is best to use a full domain name (e.g. Node.Subd.Domain). However, you may have to use the IP address itself, if your host does not have a way to resolve the address via DNS. If you have the luxury of fixed addresses (eg: you are not using DHCP), then it can be helpful to add two entries for each TCP/IP host, one that specifies the host name and one that specifies the host address.
  • There are various TCP/IP packages for OpenVMS, and you must use syntax appropriate to the transport installed.
  • If a TCP/IP connection is still not working, ensure that the transport you want has been activated for use with DECwindows. See Section 11.14 for details of configuring TCP/IP as a transport.
• There is a log file created in SYS$MANAGER: which can tell you which transports are loaded, and also tell you what connect attempts were rejected, including showing what the presented credentials were. This file is SYS$MANAGER:DECW$SERVER_0_ERROR.LOG, although the 0 could be another number if you have multiple servers on the workstation. I have found this file to be very useful for tracking down what needs to be put in the Session Manager Security entries.

To create a display from an OpenVMS host to a remote X Windows display, use one of the following DCL commands:

$ SET DISPLAY /CREATE /TRANSPORT=net_transport /NODE=remote_node $ SET DISPLAY /CREATE /TRANSPORT=LAT /NODE=remote_node $ SET DISPLAY /CREATE /TRANSPORT=DECnet /NODE=remote_node $ SET DISPLAY /CREATE /TRANSPORT=TCPIP /NODE=remote_node

Note that LAT is typically used only for the VXT series X Windows terminals, but it can also be used from OpenVMS to OpenVMS systems on various OpenVMS releases, such as on OpenVMS Alpha V6.1 and later. For details on configuring the TCP/IP transport, see Section 11.14.

If you are interested in X Windows terminals and have an older VAXstation system around, please see the EWS package on Freeware V5.0.

11.3 How can I get the information from SHOW DISPLAY into a symbol?

Use the undocumented SHOW DISPLAY/SYMBOL, and then reference the symbols DECW$DISPLAY_NODE, DECW$DISPLAY_SCREEN, DECW$DISPLAY_SERVER and/or DECW$DISPLAY_TRANSPORT.

An example of calling the underlying (and also undocumented) sys$qio programming interface for the WSDRIVER (WSAn:) is available at:

http://www.hp.com/go/openvms/freeware/

Look in the Freeware V4.0 directory /srh_examples/DECUS_UNDOC_CLINIC/.

11.4 How do I get a log of a DECterm session?

If you are working from a DECwindows DECterm terminal emulator, you can use the AutoPrint feature. Choose the "Printer..." menu item from the "Options" menu, set the printing destination to the name of the file you want, and set "Auto Print Mode". You are now free to continue.

It should be noted that all of the characters and escape sequences are captured, but if you display the resulting log file on a DECterm, then you will see exactly what was originally displayed.

You can also use the "Print Screen" screen capture available in the DECwindows session manager menus, if you simply wish to snapshot a particular portion of the X Windows display.

If you are using the Freeware VTstar terminal emulator package, you will find a similar logging mechanism is available in the menus.

11.5 Why is DECwindows Motif not starting?

First check to see if there is a graphics device, usually a G* device. (eg: On a DEC 2000 model 300, use the command SHOW DEVICE GQ) If you do not find a graphics device:

• OpenVMS has failed to find the appropriate IRQ information for an EISA graphics card (on the DEC 2000 series) such as the HP (Compaq) QVision, and did not autoconfigure it. Run the correct ECU (for Tru64 UNIX and OpenVMS) and reboot. This is necessary only on EISA-based systems.
• You have an EISA-based system (such as the DEC 2000 model 300) and do not have a HP (Compaq) QVision video card. This EISA graphics card should have Compaq printed on it, and identifies itself as a CPQ3011 or a CPQ3111. If it is not one of these two EISA devices, then OpenVMS does not support it. (There are no other supported EISA graphics controllers, and EISA graphics are normally used with DECwindows only on the DEC 2000 series systems.)
• You have a PCI-based system, and do not have a supported graphics controller---examples of supported controllers include the following:
  • Radeon 7500
  • PowerStorm 3D30, PowerStorm 4D20
  • 3DLabs Oxygen VX1
  
  See Section 5.16 for further information on some of these graphics controllers.
• You have booted the system minimally, or have otherwise disabled the device autoconfiguration process.

If there is a G* graphics device present:

• There may have been a severe error in the DECwindows startup. Type the contents of SYS$MANAGER:DECW$SERVER_0_ERROR.LOG for any information on errors starting the server.
• The system parameter WINDOW_SYSTEM is not set to 1. While this was a common way for system managers to disable the DECwindows server startup, it is not particularly reliable as DECwindows can now "correct" this setting.
  If you really do not want an OpenVMS system with workstation hardware to bootstrap and configure itself as a workstation, add the following definition to SYLOGICALS.COM:

  $ DEFINE/SYSTEM/EXEC DECW$IGNORE_WORKSTATION TRUE

• You may not have a valid DECwindows Motif license loaded. To check for the two most common types of Motif product authorization keys (PAKs), use the following DCL commands:

  $ LICENSE LIST DW-MOTIF/FULL $ LICENSE LIST NET-APP-SUP*/FULL

  
  and examine the information displayed. Make sure that one of these licenses is present, valid and active.
  For information on registering software license product authorization keys (PAKs) when you cannot log into the system directly, please see Section 5.6.2.

• Check that the DECW$PRIVATE_SERVER_SETUP.COM is correct for the graphics controller in use. For instance:
  The following is from the 9FX Vision 330 Owners Guide, EK-V330G-OG pg 2-9. Place the following in DECW$PRIVATE_SERVER_SETUP.COM, creatibng .COM from .TEMPLATE if necessary. Locate the DECW$PRIVATE_SERVER_SETUP.COM file in SYS$SPECIFIC:[SYSMGR] or in SYS$COMMON:[SYSMGR] as appropriate; the former file is used for this system within a cluster configuration, and the latter is used for all systems that do not also have a local copy of this file in SYS$SPECIFIC:[SYSMGR].

  $ DECW$XSIZE_IN_PIXELS == xvalue $ DECW$YSIZE_IN_PIXELS == yvalue $ DEFINE/SYSTEM DECW$SERVER_REFRESH_RATE rate_in_Hz

  
  Also see Section 11.11. Details of the PowerStorm 3D30 and 4D20 settings are available in the OpenVMS Ask The Wizard area.