=;The OpenVMS Frequently Asked Questions (FAQ)D

The OpenVMS Frequently Asked Questions (FAQ)



 r \ ^  
PreviousContentsIndex

p

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



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

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

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

4For further floating-point related information, see:

q

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



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

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

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



?Many software developers desire to use a unique hardware ID to E"lock" a given copy of their product to a specific system. =Most VAX and Alpha systems do not have a unique hardware-set D"system ID" that can be used for this purpose. HP OpenVMS Cproducts 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.

FHP OpenVMS uses a software-based system called the License Management GFacility (LMF). This provides for software keys (Product Authorization FKeys or PAKS) which support capacity and user-based license checking. eHP offers an LMF PAK Generator to CSA members---see Section 2.13.

[For information on licensing, please see Section 12.4.

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



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see 0Section 3.8.u

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



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

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

DShareable images contain code executed indirectly, these images are Freferenced from executable images and/or from other shareable images. EThese images can not grant enhanced privileges, even with the use of INSTALL with /PRIVILEGEL 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.H (See `protected images' for information on `privileged shareable  images'.)

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

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

FLoadable images and device drivers are images that can be used to add Gcode into the OpenVMS kernel. Pseudo-device drivers are a particularly Fconvenient way to add executable code, with associated driver-defined Hdata 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.

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



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see 0Section 3.8.e

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



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

10.13 What is a descriptor?



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

HThe following are examples of creating and using descriptors in C, with Athe use of the angle brackets normally expected by the C include 5statements 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 = 1      { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL }; #    struct dsc$descriptor DynDsc = 1      { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };     int DynDscLen = 255; 1    $DESCRIPTOR( ConstDsc, "This is a string" );  0    /* finish setting up a static descriptor */ *    StaticDsc.dsc$w_length      = TXTSIZ; 3    StaticDsc.dsc$a_pointer     = (void *) TxtBuf;  1    /* 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; 




HStatic descriptors reference storage entirely under application program Bcontrol, and the contents of the descriptor data structure can be Cmodified as required (by the application). OpenVMS routines do not Bmodify the contents of a static descriptor, nor do they alter the Daddress or length values stored in the static descriptor. (The term F"static" refers to the descriptor data structure, and not necessarily -to the storage referenced by the descriptor.)

HDynamic descriptors reference storage under the control of the run-time Hlibrary, and the contents of a dynamic descriptor data structure---once Einitialized---can only be modified under control of run-time library Froutines. The dynamic storage referenced by the dynamic descriptor is Callocated and maintained by the run-time library routines. Various >OpenVMS routines do alter the contents of the descriptor data Dstructure, changing the value for the amount and the address of the Fstorage associated with the dynamic descriptor, as required. Routines Fcan obviously access and alter the contents of the storage referenced by the descriptor.

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

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

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

o

10.14 How do I create a process under another username?



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

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

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

ATypical mechanisms for creating a process under another username include:



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

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



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

7Detached processes typically do not have a CLI present.

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

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

BAlso note that the lib$spawn and the C system call will fail in a GCAPTIVE 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?



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

ABliss language source code that contains the following statement:

 

"
%  LIBRARY 'SYS$LIBRARY:STARLET.L32'; 




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

6STARLET.L32 contains the public interfaces to OpenVMS:

 

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




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

 

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




2The equivilent files for Bliss64 are created with:

 

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




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

 

"
! 8! 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 5! 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  PMACRO EVAX =                    ! = 1 if compiled BLISS/E* (Obsolete, old name) M        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn  KMACRO ALPHA =                   ! = 1 if compiled BLISS/E* (New arch name) M        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn  KMACRO IA64 =                    ! = 1 if compiled BLISS/I* (New arch name) P        (%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /Ann  MACRO ADDRESSBITS = D        %BPADDR%;               ! = 32 or 64 based on compiler used  




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

 

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


f

10.17 How can I open a file for shared access?



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

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



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see 0Section 3.8.

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

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



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

10.19 How do I activate the OpenVMS Debugger from an application?



 

"
#include {lib$routines.h} #include {ssdef.h} #include {string.h}  main()     { $    char ascic_debug_commands[128]; *    char *dbgcmd = "*show calls;go;exit";  ,    strcpy( ascic_debug_commands, dbgcmd ); ;    ascic_debug_commands[0] = (char) strlen( dbgcmd ) - 1;  2    lib$signal(SS$_DEBUG,1,ascic_debug_commands);      return 1;     } 




nAlso see Section 10.28 for another related discussion of the OpenVMS <Debugger, and of a technique that uses the SS$_DEBUG signal.W

10.20 Dealing with Endian-ness?



EOpenVMS VAX, OpenVMS Alpha and OpenVMS I64 (as well as all Microsoft HWindows implementations) all support and all use the little-endian byte Bordering. Certain Alpha microprocessors and certain Intel Itanium Fprocessors can be configured to operate in big-endian and potentially 7in bi-endian mode. HP-UX typically operates big-endian.

HWith little-endian byte order, the least significant byte is always the Afirst byte; the byte at the lowest address. With big-endian byte Gordering, the byte storage order in memory is dependent on the size of 9the data (byte, word, longword) that is being referenced.

HEndian-ness is a problem has been solved many times before. Some of the Htypical solutions include htonl/htons and ntohl/ntohs in the standard C Clibrary and the TCP/IP Services XDR (eXternal Data Representation) Hlibraries. One of the more recently introduced network formats, and one >that is seeing extensive press and marketing coverage, is XML.d

10.21 How to resolve LINK-I-DATMISCH errors?



EThe message LINK-I-DATMISCH is informational, and indicates that the Gversion of the specified shareable image found in the system shareable Gimage directory does not match the version of the shareable image that Fwas originally loaded into IMAGELIB.OLB, one of the OpenVMS libraries !typically searched by the LINKER.

GFrom a privileged username, you can usually completely repair this via the following DCL command:

 

"
B$ LIB/REPLACE/SHARE SYS$LIBRARY:IMAGELIB.OLB SYS$SHARE:LIBRTL.EXE 




DThis command assumes that the shareable image that was found in the HSYS$SHARE: area is valid and upward-compatiable, and that the image has @simply replaced an older version without also updating IMAGELIB.q

10.22 HP C and other OpenVMS C Programming Considerations?



DVAX C V3.2 was released for OpenVMS VAX systems in 1991. DEC C V4.0 Areplaced VAX C V3.2 in 1993 as the HP C compiler for OpenVMS VAX Fsystems. HP C is the ANSI C compiler for OpenVMS Alpha systems. VAX C Bpredates the ANSI C standards, and has various areas that are not Hcompliant with ANSI C requirements. HP C is an ANSI C compiler, and can Halso compile most VAX C code when /STANDARD=VAXC is specified. Versions Hof this compiler between V3.2 and V6.5 (exclusive) were known as DEC C, DIGITAL C, and Compaq C.

EBoth compilers can be installed at the same time on the same OpenVMS GVAX system, allowing a migration from VAX C to DEC C, and allowing the <same DEC C code to be used on OpenVMS VAX and OpenVMS Alpha.

FThe system manager can choose the system default C compiler when HP C Gis installed on a system with VAX C, and a C programmer can explicitly >select the required compiler for a any particular compilation.

FA current "C" license PAK allows access to both VAX C and HP C on the same OpenVMS VAX system.

HVarious HP C versions can be installed on OpenVMS VAX V5.5-2 and later. >OpenVMS VAX releases such as V5.5-2 and V6.0 will require the Einstallation of a HP C RTL kit, a kit that is included with the HP C Hcompiler. OpenVMS VAX versions V6.1 and later do not require a seperate GRTL kit, but HP C RTL ECO kits are available to resolve problems found +with the C RTL on various OpenVMS releases.

GWith HP C, for automatic resolution of the standard C library routines :by the LINKER utility, use the /PREFIX qualifier, such as E/PREFIX=ALL_ENTRIES. If a particular application program replaces an Dexisting C library routine, use /PREFIX=(ALL_ENTRIES,EXCEPT=(...)). F(VAX C required explicit specification of an RTL shareable image or C object library during the link.)

GWhen the /PREFIX is requested, the compiler generates a "decc$" prefix Gon the specified symbols. This prefix allows the LINKER to resolve the Fexternal symbols against the symbols present in the DECC$SHR library. EThe DECC$SHR library is included in the IMAGELIB.OLB shareable image Glibrary, and IMAGELIB is searched by default when any program (written Cin any language) is LINKed. Because the standard C library routine Enames are very likely to match application routines written in other Elanguages, a prefix "decc$" is added to the C symbol names to assure Btheir uniqueness; to prevent symbol naming conflicts. C programs, Hhowever, can sometimes have private libraries for various purposes, and Dthe external routines share the same names as the library routines. E(This is not recommended, but there are applications around that use Gthis technique.) Thus the need to explicity specify whether or not the G"decc$" prefix should be prepended to the external symbol names by the compiler.

HThe qualifiers, and most (all?) with associated pragmas, that may be of 3interest when migrating VAX C code to HP C include:






 r Y \ ^  
PreviousNextContentsIndex