f. OpenVMS FAQ -&- page 15)b @5z

HP OpenVMS Systems Documentation

 q> $"b,
Content starts here"D

The OpenVMS Frequently Asked Questions (FAQ)


 l n  
PreviousContentsIndex

p

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



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

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

FThere are floating-point conversion source code packages available forvarious platforms.

4For further floating-point related information, see:

q

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



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

GNote that omitting arguments to Fortran routines is non-standard and isFunsupported. 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 toD"lock" a given copy of their product to a specific system.<Most VAX and Alpha systems do not have a unique hardware-setC"system ID" that can be used for this purpose. HP OpenVMSBproducts 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.

EHP OpenVMS uses a software-based system called the License ManagementFFacility (LMF). This provides for software keys (Product AuthorizationEKeys or PAKS) which support capacity and user-based license checking.uHP offers an LMF PAK Generator to CSA members---see Section 2.13.

kFor information on licensing, please see Section 12.4.

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



GFor additional information on the OpenVMS Ask The Wizard (ATW) area andAfor a pointer to the available ATW Wizard.zip archive, please see@Section 3.8.u

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



FExecutable code in OpenVMS typically resides in an image---an image isBa file---the file extension is typically .EXE---that contains thisAcode. Common types of images include executable images, shareable3images, system images, and protected (UWSS) images.

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

CShareable images contain code executed indirectly, these images areEreferenced from executable images and/or from other shareable images.DThese images can not grant enhanced privileges, even with the use ofINSTALL with /PRIVILEGEK or a subsystem identifier. These shareable images can be dynamically9 activated (a LINK that occurs at run-time) via the< LIB$FIND_IMAGE_SYMBOL run-time library (RTL) routine.G (See `protected images' for information on `privileged shareable images'.)

>System images are intended to run directly on the VAX or AlphaEhardware---these are normally used for the kernel code that comprisesan operating system.

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

ELoadable images and device drivers are images that can be used to addFcode into the OpenVMS kernel. Pseudo-device drivers are a particularlyEconvenient way to add executable code, with associated driver-definedGdata structures, into the kernel. The pseudo-device driver includes theUCB 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.

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



GFor additional information on the OpenVMS Ask The Wizard (ATW) area andAfor a pointer to the available ATW Wizard.zip archive, please see@Section 3.8.e

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



CThere are several options available for copying files from within a=program. Obvious choices include using lib$spawn(), system(),Gsys$sndjbc() or sys$creprc() to invoke a DCL COPY command. Other commonGalternatives include using the callable convert routines and the BACKUP3application programming interface (V7.1 and later).S

10.13 What is a descriptor?



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

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




GStatic descriptors reference storage entirely under application programAcontrol, and the contents of the descriptor data structure can beBmodified as required (by the application). OpenVMS routines do notAmodify the contents of a static descriptor, nor do they alter theCaddress or length values stored in the static descriptor. (The termE"static" refers to the descriptor data structure, and not necessarily-to the storage referenced by the descriptor.)

GDynamic descriptors reference storage under the control of the run-timeGlibrary, and the contents of a dynamic descriptor data structure---onceDinitialized---can only be modified under control of run-time libraryEroutines. The dynamic storage referenced by the dynamic descriptor isBallocated and maintained by the run-time library routines. Various=OpenVMS routines do alter the contents of the descriptor dataCstructure, changing the value for the amount and the address of theEstorage associated with the dynamic descriptor, as required. RoutinesEcan obviously access and alter the contents of the storage referencedby the descriptor.

@OpenVMS languages that include support for strings or arrays areFexpected to use descriptors for the particular structure. Most OpenVMS>languages, such as Fortran and BASIC, use descriptors entirelyEtransparently. Some, like DEC C, require the programmer to explicitly#create and maintain the descriptor.

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

CFortran defaults to passing integers by reference and characters byCdescriptor. The following sites discuss mixing Fortran and C sourcecode in the same application:

o

10.14 How do I create a process under another username?



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

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

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

@Typical mechanisms for creating a process under another usernameinclude:

    <
  • personna services around a sys$creprc call. See above.G
  • via DECnet task-to-task, using explicit specification of usernameH and password, or using a DECnet proxy. This creates a network-mode jobI under the target user. The network-mode job might do little more than aB RUN/DETACH of an image passed in via task-to-task---task-to-task> communications are fully available using strictly DCL-to-DCL9 processing, or using a compiled language and DCL, etc.)H
  • SUBMIT/USER, or the username argument on the sys$sndjbc call. ThisG creates a batch-mode job under the specified username. The batch-modeH job might do little more than a RUN/DETACH of an image passed in via a parameter.I
  • the UIC argument on the sys$creprc call. This mimics the UIC of theI target user, and is certainly not the prefered mechanism for this task.
  • Via pseudo-terminals...


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

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

_

cFThe processing within run-time library (RTL) calls such as lib$attach,Blib$disable_ctrl, lib$do_command, lib$enable_ctrl, lib$get_symbol,Clib$run_program, lib$set_symbol, lib$set_logical, and lib$spawn, isu<dependent on and requires the presence of a command languageDinterpreter (CLI), such as DCL. Without a CLI present in the currentGprocess, these calls will fail with a "NOCLI, no CLI present to performdfunction" error.

-7Detached processes typically do not have a CLI present.t

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

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

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

e=

yCThe Bliss language compilers and documentation are available on thelOpenVMS Freeware distributions.l>

nABliss language source code that contains the following statement:d

o 
S
"
$  LIBRARY 'SYS$LIBRARY:STARLET.L32';

n


o>or similar requires the presence of the Bliss libraries. TheseBlibraries are created on the target system using the Bliss require8files, and are built using the following Bliss commands:

6STARLET.L32 contains the public interfaces to OpenVMS:meo

m 
m
"
5    $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L32 -        SYS$LIBRARY:STARLET.REQs

a


fCLIB.L32 contains both the public and private interfaces to OpenVMS:f>pmp

h 

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

r


a2The equivilent files for Bliss64 are created with:ne hn

a 
t
"
4    $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]LIB.L64 -3        SYS$LIBRARY:LIB.R64+STARLET.REQ+STARLET.R64,8    $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L64 -        SYS$LIBRARY:STARLET.R64V

d


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

9 
u
"
! 7! This is the OpenVMS VAX version of ARCH_DEFS.REQ, anda:! contains the architectural definitions for conditionally9! compiling OpenVMS Bliss sources for use on VAX systems.c:! (If you should encounter compilation errors here, please4! seriously consider upgrading your Bliss compiler.)!nMACRO VAXPAGE = 1%;hMACRO BIGPAGE = 0%;r!u;MACRO VAX =                     ! = 1 if compiled BLISS/VAX/?        %BLISS(BLISS32V)%;      ! = 0 if not compiled BLISS/VAXeOMACRO EVAX =                    ! = 1 if compiled BLISS/E* (Obsolete, old name)tL        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /InnJMACRO ALPHA =                   ! = 1 if compiled BLISS/E* (New arch name)L        (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /InnJMACRO IA64 =                    ! = 1 if compiled BLISS/I* (New arch name)O        (%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /AnnlMACRO ADDRESSBITS = C        %BPADDR%;               ! = 32 or 64 based on compiler usedp

a


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

p 

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

l
f

10.17 How can I open a file for shared access?

r

1DWhen creating a file, it is often useful to allow other applicationsEand utilities---such as TYPE---to share read access to the file. Thisp@permits you to examine the contents of a log file, for instance.

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

s

aGFor additional information on the OpenVMS Ask The Wizard (ATW) area andhAfor a pointer to the available ATW Wizard.zip archive, please seeP@Section 3.8. e

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

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

LidxsaaL

mDUse the GNM tools on the OpenVMS Freeware to have common sources forDMSG (message) files and SDML (Document) documentation files. Use theEDOCUMENT command to convert the SDML documentation into the necessaryyGformats (Text, Postscript, HTML, etc). Use the MESSAGE/SDL tool (latenttEin OpenVMS) to create an SDL file based on the messages. Then use thegDSDL tool (available on the OpenVMS Freeware) to convert the SDL fileEinto language-specific definitions. (There is also a converter around0Ato convert SDL into SDML, if you want to get pictures of the datan#structures for your documentation.)ly

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

n

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

x
nhi

}Also 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?

1i

eDOpenVMS VAX, OpenVMS Alpha and OpenVMS I64 (as well as all MicrosoftGWindows implementations) all support and all use the little-endian byte=Aordering. Certain Alpha microprocessors and certain Intel ItaniumMEprocessors can be configured to operate in big-endian and potentially=7in bi-endian mode. HP-UX typically operates big-endian.tzoh)t

lGWith little-endian byte order, the least significant byte is always the_@first byte; the byte at the lowest address. With big-endian byteFordering, the byte storage order in memory is dependent on the size of9the data (byte, word, longword) that is being referenced.

mGEndian-ness is a problem has been solved many times before. Some of theoGtypical solutions include htonl/htons and ntohl/ntohs in the standard CaBlibrary and the TCP/IP Services XDR (eXternal Data Representation)Glibraries. One of the more recently introduced network formats, and oneo>that is seeing extensive press and marketing coverage, is XML.xxd

10.21 How to resolve LINK-I-DATMISCH errors?

ce

rDThe message LINK-I-DATMISCH is informational, and indicates that theFversion of the specified shareable image found in the system shareableFimage directory does not match the version of the shareable image thatEwas originally loaded into IMAGELIB.OLB, one of the OpenVMS librariesn!typically searched by the LINKER. 

rFFrom a privileged username, you can usually completely repair this viathe following DCL command:

x 
s
"
A$ LIB/REPLACE/SHARE SYS$LIBRARY:IMAGELIB.OLB SYS$SHARE:LIBRTL.EXE

r


CThis command assumes that the shareable image that was found in thelGSYS$SHARE: area is valid and upward-compatiable, and that the image hasi@simply replaced an older version without also updating IMAGELIB.cq

10.22 HP C and other OpenVMS C Programming Considerations?

T S e*hs

_CVAX C V3.2 was released for OpenVMS VAX systems in 1991. DEC C V4.0d@replaced VAX C V3.2 in 1993 as the HP C compiler for OpenVMS VAXEsystems. HP C is the ANSI C compiler for OpenVMS Alpha systems. VAX CtApredates the ANSI C standards, and has various areas that are noteGcompliant with ANSI C requirements. HP C is an ANSI C compiler, and caneGalso compile most VAX C code when /STANDARD=VAXC is specified. VersionsGof this compiler between V3.2 and V6.5 (exclusive) were known as DEC C,tDIGITAL C, and Compaq C.

eDBoth compilers can be installed at the same time on the same OpenVMSFVAX 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.

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

EA current "C" license PAK allows access to both VAX C and HP C on theesame OpenVMS VAX system.

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

oFWith HP C, for automatic resolution of the standard C library routines9by the LINKER utility, use the /PREFIX qualifier, such asD/PREFIX=ALL_ENTRIES. If a particular application program replaces anCexisting C library routine, use /PREFIX=(ALL_ENTRIES,EXCEPT=(...)).rE(VAX C required explicit specification of an RTL shareable image or Cc object library during the link.)

kFWhen the /PREFIX is requested, the compiler generates a "decc$" prefixFon the specified symbols. This prefix allows the LINKER to resolve theEexternal symbols against the symbols present in the DECC$SHR library. DThe DECC$SHR library is included in the IMAGELIB.OLB shareable imageFlibrary, and IMAGELIB is searched by default when any program (writtenBin any language) is LINKed. Because the standard C library routineDnames are very likely to match application routines written in otherDlanguages, a prefix "decc$" is added to the C symbol names to assureAtheir uniqueness; to prevent symbol naming conflicts. C programs,.Ghowever, can sometimes have private libraries for various purposes, andACthe external routines share the same names as the library routines.>D(This is not recommended, but there are applications around that useFthis technique.) Thus the need to explicity specify whether or not theF"decc$" prefix should be prepended to the external symbol names by the compiler.y

oGThe qualifiers, and most (all?) with associated pragmas, that may be ofm3interest when migrating VAX C code to HP C include:u

    H
  • Failure to specify the prefixing qualifier (on certain and usuallyI older versions of C) can cause the compiler to not add the prefixes forfG the names of the C library routines into the references placed in the H object module, which can in turn cause problems resolving the external8 symbols in the library when the object code is linked:

     

    "
    /PREFIX=ALL_ENTRIESd
    
    
    F

  • Some VAX C programs erroneously write to the string literals. By7 default, HP C does not allow the constants to change.p

    n 
    s
    "
     /ASSUME=WRITABLE_STRING_LITERALS
    
    a
    @

  • Enables sharing ("shr") of globals and of externH variables. HP C sets externs as non-shareable ("noshr"), VAX C as "shr".

     
    t
    "
    /SHARE_GLOBALS
    
    m
    =

  • VAX C assumes common block model for external linkages.u

    c 

    "
    /EXTERN_MODE=COMMON_BLOCKu
    
    d
    C

  • Refers to the padding placed between member elements within aaE struct. Disabling member alignment packs the data more tightly intopB memory, but this packaging has performance implications, both on8 OpenVMS VAX and particularly on OpenVMS Alpha systems.

    r 
    c
    "
    /[NO]MEMBER_ALIGNMENTh
    
    l
    7

  • Enable all manner of useful compiler diagnostics:r

     
    o
    "
    D/WARN=ENABLE=(LEVEL4,QUESTCODE)/STANDARD=PORT/ACCEPT=NOVAXC_KEYWORDS
    
    e
    B
    You can disable extraneous diagnostics with the following:

    i 
    a
    "
    #ifdef __DECC$#pragma message save5#pragma message disable /* insert message tag here */n#endif
    
    e
    

as




 i l n  a
PreviousNextContentsIndex

 

y#g6aa