The OpenVMS Frequently Asked Questions (FAQ)


Previous Contents Index

10.5 How do I link against SYS$SYSTEM:SYS.STB on an Alpha system?

LINK/SYSEXE is the OpenVMS Alpha equivalent of linking against SYS.STB. This links against the base image: SYS$BASE_IMAGE.EXE

Also see Section 10.11, particularly for pointers to the details on shareable images and shareable image creation, and see Section 10.22 for details of inner-mode floating point requirements, of data alignment, requirements for use of /NOSYSLIB, and other related inner-mode programming details, and see Section 10.11 for image-related information.

10.6 How do I do a SET DEFAULT from inside a program?

The problem is that SYS$SETDDIR only changes the default directory - NOT the default disk. The default disk is determined by the logical SYS$DISK. If you want to change the default disk within a program, then call LIB$SET_LOGICAL to change the logical SYS$DISK. You will need to call both LIB$SET_LOGICAL and SYS$SETDDIR to change both default disk and the default directory!

10.7 How do I turn my Fortran COMMON into a shareable image on Alpha?

You need to add SYMBOL_VECTOR=(<common-name>=PSECT) to your options file. On OpenVMS VAX all OVR/REL/GBL psects were automatically exported into the shareable image's Global Symbol Table. On OpenVMS Alpha you have to tell the linker that you want this done by means of the PSECT keyword in the SYMBOL_VECTOR options file statement.

This has several advantages over OpenVMS VAX. First, you don't have to worry about the address of the psect when you try to create a new, upwardly compatible version of the shareable image. Second, you can control which psects, if any, are made visible outside the shareable image.

By default, COMMON PSECTs in HP Fortran for OpenVMS Alpha (as well as most other OpenVMS Alpha compilers) are NOSHR. On VAX, the default was SHR which required you to change the attribute to NOSHR if you wanted your COMMON to be in a shareable image but not write-shared by all processes on the system. If you do want write-sharing, use:


CDEC$ PSECT common-name=SHR 

in the Fortran source code (the CDEC$ must be begin in column 1) or a linker options file PSECT_ATTR statement to set the COMMON PSECT attribute to SHR.

For further information, see the Linker manual.

10.8 How do I convert between IEEE and VAX floating data?

In OpenVMS V6.1 and later, the routine CVT$CONVERT_FLOAT is documented in the LIB$ Run-Time Library Reference Manual, and can perform floating point conversions between any two of the following floating datatypes: VAX (F,D,G,H), little-endian IEEE (single, double, quad), big-endian IEEE (single, double, quad), CRAY and IBM System\370, etc.

HP Fortran (all OpenVMS platforms) has a feature which will perform automatic conversion of unformatted data during input or output. See the HP Fortran documentation for information on "non-native data in I/O" and the CONVERT= OPEN statement keyword.

There are floating-point conversion source code packages available for various platforms.

For further floating-point related information, see:

10.9 How do I get the argument count in a Fortran routine?

On VAX, many programmers would use a MACRO routine which accessed the AP register of the caller to get the address of the argument list and hence the argument count. This was not guaranteed to work on VAX, but usually did. However, it doesn't work at all on OpenVMS Alpha, as there is no AP register. On Alpha systems, you must use a language's built-in function to retrieve the argument count, if any. In Fortran this is IARGCOUNT, which is also available in DEC Fortran on OpenVMS VAX.

Note that omitting arguments to Fortran routines is non-standard and is unsupported. It will work in many cases - read the DEC Fortran release notes for additional information.

10.10 How do I get a unique system ID for licensing purposes?

Many software developers desire to use a unique hardware ID to "lock" a given copy of their product to a specific system. Most VAX and Alpha systems do not have a unique hardware-set "system ID" that can be used for this purpose. HP OpenVMS products do not use hardware IDs in the licensing methods, as many users consider a hardware-based licensing scheme to be negative attribute when considering software purchases.

HP OpenVMS uses a software-based system called the License Management Facility (LMF). This provides for software keys (Product Authorization Keys or PAKS) which support capacity and user-based license checking. HP offers an LMF PAK Generator to DSPP (formerly CSA) members---see Section 2.8.3 for general details on the DSPP offerings, and on the DSPP-provided Freeware PAKGEN PAK that is available for those that are interested in details. (Sorry, no; you can't use the Freeware PAKGEN PAK to generate any PAK you might want. Folks at HP also thought of that one, too.)

For information on licensing, please see Section 12.4.

However, if a hardware-based method is required, the most common method is based on an Ethernet adaptor hardware address. Sample source code for implementing this is available at:

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. ATW has been superceded (for new questions) by the ITRC discussion forums; the area remains available for reference.

10.11 What is an executable, shareable, system or UWSS image?

Executable code in OpenVMS typically resides in an image---an image is a file---the file extension is typically .EXE---that contains this code. Common types of images include executable images, shareable images, system images, and protected (UWSS) images.

Executable images are programs that can be directly executed. These images can grant enhanced privileges, with an INSTALL of the image with /PRIVILEGE, or can grant enhanced access with the specification of a subsystem identifier on the ACL associated with the image.

Shareable images contain code executed indirectly, these images are referenced from executable images and/or from other shareable images. These images can not grant enhanced privileges, even with the use of INSTALL with /PRIVILEGE or a subsystem identifier. These shareable images can be dynamically activated (a LINK that occurs at run-time) via the LIB$FIND_IMAGE_SYMBOL run-time library (RTL) routine. (See `protected images' for information on `privileged shareable images'.)

System images are intended to run directly on the VAX or Alpha hardware---these are normally used for the kernel code that comprises an operating system.

Protected images---also refered to as User-Written System Services (UWSS), or as privileged shareable images---are similiar in some ways to a standard shareable images, but these images include a `change mode' handler, and execute in an `inner' processor mode (privileged mode; executive or kernel), and code executing in inner modes has implicit SETPRV privilege. Must be INSTALLed with /PROTECT. Note that inner-mode code has restrictions around calling library routines, around calling various system services, and around calling code located in other protected or shareable images.

Loadable images and device drivers are images that can be used to add code into the OpenVMS kernel. Pseudo-device drivers are a particularly convenient way to add executable code, with associated driver-defined data structures, into the kernel. The pseudo-device driver includes the UCB and DDB data structures, and a calling interface with support for both privileged and unprivileged access to the driver code via sys$qio[w] calls.

A cookbook approach to creating OpenVMS shareable images is available at the URL:

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. ATW has been superceded (for new questions) by the ITRC discussion forums; the area remains available for reference.

10.12 How do I do a file copy from a program?

There are several options available for copying files from within a program. Obvious choices include using lib$spawn(), system(), sys$sndjbc() or sys$creprc() to invoke a DCL COPY command. Other common alternatives include using the callable convert routines and the BACKUP application programming interface (V7.1 and later).

10.13 What is a descriptor?

A descriptor is a data structure that describes a string or an array. Each descriptor contains information that describes the type of the data being referenced, the size of the data, and the address of the data. It also includes a description of the storage used for the data, typically static or dynamic. Descriptors are passed by reference.

The following are examples of creating and using descriptors in C, with the use of the angle brackets normally expected by the C include statements deliberately altered in deference to HTML:


    #include {descrip.h} 
    #include {lib$routines.h} 
    #include {stsdef.h} 
    int RetStat; 
    char TxtBuf[TXTSIZ] 
    struct dsc$descriptor StaticDsc = 
      { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL }; 
    struct dsc$descriptor DynDsc = 
      { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL }; 
    int DynDscLen = 255; 
    $DESCRIPTOR( ConstDsc, "This is a string" ); 
 
    /* finish setting up a static descriptor */ 
    StaticDsc.dsc$w_length      = TXTSIZ; 
    StaticDsc.dsc$a_pointer     = (void *) TxtBuf; 
 
    /* finish setting up a dynamic descriptor */ 
    RetStat = lib$sget1_dd( &DynDscLen, &DynDsc ); 
    if ( !$VMS_STATUS_SUCCESS( RetStat ) ) 
      return RetStat; 
 
    /* release the dynamic storage */ 
    RetStat = lib$sfree1_dd( &DynDsc ); 
    if (!$VMS_STATUS_SUCCESS( RetStat )) 
      return RetStat; 

Static descriptors reference storage entirely under application program control, and the contents of the descriptor data structure can be modified as required (by the application). OpenVMS routines do not modify the contents of a static descriptor, nor do they alter the address or length values stored in the static descriptor. (The term "static" refers to the descriptor data structure, and not necessarily to the storage referenced by the descriptor.)

Dynamic descriptors reference storage under the control of the run-time library, and the contents of a dynamic descriptor data structure---once initialized---can only be modified under control of run-time library routines. The dynamic storage referenced by the dynamic descriptor is allocated and maintained by the run-time library routines. Various OpenVMS routines do alter the contents of the descriptor data structure, changing the value for the amount and the address of the storage associated with the dynamic descriptor, as required. Routines can obviously access and alter the contents of the storage referenced by the descriptor.

OpenVMS languages that include support for strings or arrays are expected to use descriptors for the particular structure. Most OpenVMS languages, such as Fortran and BASIC, use descriptors entirely transparently. Some, like DEC C, require the programmer to explicitly create and maintain the descriptor.

For further information on string descriptors, see the OpenVMS Programming Concepts manual, part of the OpenVMS documentation set.

Fortran defaults to passing integers by reference and characters by descriptor. The following sites discuss mixing Fortran and C source code in the same application:

10.14 How do I create a process under another username?

Many server processes can operate within the context of the target user using privileges, using calls such as sys$chkpro and (more commonly in this context) sys$check_access as needed to determine if access would be permitted for the specified user within the current security model.

With OpenVMS V6.2 and later, the persona system services (SYS$PERSONA_*) can be used to assume the persona of the specified user---these allow the server to operate as the specified user, in a controlled fashion. The persona services can be used as a "wrapper" around a sys$creprc process creation call, as well---this will create a seperate process entirely under the assumed persona.

Information on the persona system services is included in the OpenVMS V6.2 new features documentation, and in the OpenVMS V7.1 and later system services documentation. These system services exist and are supported in OpenVMS V6.2 and later releases.

Typical mechanisms for creating a process under another username include:

There are likely a few other mechanisms around... There are various tools available from DECUS and other sources that allow various forms of user impersonation, as well. These tools will require version-dependent kernel code and enhanced privileges for some of (or all of) their operations.

10.15 Why do lib$spawn, lib$set_symbol fail in detached processes?

The processing within run-time library (RTL) calls such as lib$attach, lib$disable_ctrl, lib$do_command, lib$enable_ctrl, lib$get_symbol, lib$run_program, lib$set_symbol, lib$set_logical, and lib$spawn, is dependent on and requires the presence of a command language interpreter (CLI), such as DCL. Without a CLI present in the current process, these calls will fail with a "NOCLI, no CLI present to perform function" error.

Detached processes typically do not have a CLI present.

In place of lib$spawn, sys$creprc can often be used. The context of the parent process (symbols and logical names) will not be propogated into the subprocess when sys$creprc is used, though when there is no CLI present in the process this (lack of) propogation is moot.

To create a detached process with a CLI, you must specify LOGINOUT as the target image as discussed elsewhere in the FAQ, or only use these calls (and any other calls requiring a CLI) from images that are running in an "interactive", "batch", or "other" mode process.

Also note that the lib$spawn and the C system call will fail in a CAPTIVE login environment. The lib$spawn call can be gotten to work in this environment with the specification of the TRUSTED flag.

10.16 Where can I obtain Bliss, and the libraries and supporting files?

The Bliss language compilers and documentation are available on the OpenVMS Freeware distributions.

Bliss language source code that contains the following statement:


  LIBRARY 'SYS$LIBRARY:STARLET.L32'; 

or similar requires the presence of the Bliss libraries. These libraries are created on the target system using the Bliss require files, and are built using the following Bliss commands:

STARLET.L32 contains the public interfaces to OpenVMS:


    $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L32 - 
        SYS$LIBRARY:STARLET.REQ 

LIB.L32 contains both the public and private interfaces to OpenVMS:


    $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]LIB.L32 - 
        SYS$LIBRARY:LIB.REQ+SYS$LIBRARY:STARLET.REQ 

The equivilent files for Bliss64 are created with:


    $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]LIB.L64 - 
        SYS$LIBRARY:LIB.R64+STARLET.REQ+STARLET.R64 
    $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L64 - 
        SYS$LIBRARY:STARLET.R64 

Some Bliss code may also require the OpenVMS VAX architecture flags. The following is the equivilent of the Alpha ARCH_DEFS.REQ module:


! 
! This is the OpenVMS VAX version of ARCH_DEFS.REQ, and 
! contains the architectural definitions for conditionally 
! compiling OpenVMS Bliss sources for use on VAX systems. 
! (If you should encounter compilation errors here, please 
! seriously consider upgrading your Bliss compiler.) 
! 
MACRO VAXPAGE = 1%; 
MACRO BIGPAGE = 0%; 
! 
MACRO VAX =                     ! = 1 if compiled BLISS/VAX 
        %BLISS(BLISS32V)%;      ! = 0 if not compiled BLISS/VAX 
 
MACRO EVAX =                    ! = 1 if compiled BLISS/E* (Obsolete, old name) 
        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn 
 
MACRO ALPHA =                   ! = 1 if compiled BLISS/E* (New arch name) 
        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn 
 
MACRO IA64 =                    ! = 1 if compiled BLISS/I* (New arch name) 
        (%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /Ann 
 
MACRO ADDRESSBITS = 
        %BPADDR%;               ! = 32 or 64 based on compiler used 
 

Some Bliss code may require the definition files for the OpenVMS older LIBRTL routine lib$tparse, or the newer lib$table_parse call:


    $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]TPAMAC.L32 - 
        SYS$LIBRARY:TPAMAC.REQ 

10.17 How can I open a file for shared access?

When creating a file, it is often useful to allow other applications and utilities---such as TYPE---to share read access to the file. This permits you to examine the contents of a log file, for instance.

A C source example that demonstrates how to do this is available in topic (2867) in the OpenVMS Ask The Wizard area:

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. ATW has been superceded (for new questions) by the ITRC discussion forums; the area remains available for reference.

Depending on the environment, you may need to use C calls such as fsync and fflush, and---in specific cases---the setvbuf(_IONBF) call.

For related materials around commands that can potentially be used to override file locking---to view the file contents as currently written to disk---see Section 9.12.

10.18 How can I have common sources for messages, constants?

Use the GNM tools on the OpenVMS Freeware to have common sources for MSG (message) files and SDML (Document) documentation files. Use the DOCUMENT command to convert the SDML documentation into the necessary formats (Text, Postscript, HTML, etc). Use the MESSAGE/SDL tool (latent in OpenVMS) to create an SDL file based on the messages. Then use the SDL tool (available on the OpenVMS Freeware) to convert the SDL file into language-specific definitions. (There is also a converter around to convert SDL into SDML, if you want to get pictures of the data structures for your documentation.)


Previous Next Contents Index