             2                    OpenVMS Programming Information        =                    o  via DECnet task-to-task, using explicit F                       specification of username and password, or usingE                       a DECnet proxy. This creates a network-mode job G                       under the target user. The network-mode job might I                       do little more than a RUN/DETACH of an image passed E                       in via task-to-task-task-to-task communications C                       are fully available using strictly DCL-to-DCLaG                       processing, or using a compiled language and DCL,i                       etc.)c  B                    o  SUBMIT/USER, or the username argument on theJ                       sys$sndjbc call. This creates a batch-mode job underI                       the specified username. The batch-mode job might dolI                       little more than a RUN/DETACH of an image passed int&                       via a parameter.  J                    o  the UIC argument on the sys$creprc call. This mimicsJ                       the UIC of the target user, and is certainly not the7                       prefered mechanism for this task.,  -                    o  Via pseudo-terminals...   D                    There are likely a few other mechanisms around...I                    There are various tools available from DECUS and other J                    sources that allow various forms of user impersonation,F                    as well. These tools will require version-dependentJ                    kernel code and enhanced privileges for some of (or all(                    of) their operations.  D           __________________________________________________________B           10.15  Why do lib$spawn, lib$set_symbol fail in detached                  processes?.  E                    The processing within run-time library (RTL) callseH                    such as lib$attach, lib$disable_ctrl, lib$do_command,D                    lib$enable_ctrl, lib$get_symbol, lib$run_program,E                    lib$set_symbol, lib$set_logical, and lib$spawn, is F                    dependent on and requires the presence of a commandI                    language interpreter (CLI), such as DCL. Without a CLIdH                    present in the current process, these calls will failE                    with a "NOCLI, no CLI present to perform function"l                    error.   J                    Detached processes typically do not have a CLI present.  J                                                                      10-13 s  l          2                    OpenVMS Programming Information        G                    In place of lib$spawn, sys$creprc can often be used.II                    The context of the parent process (symbols and logicalrI                    names) will not be propogated into the subprocess wheneJ                    sys$creprc is used, though when there is no CLI presentE                    in the process this (lack of) propogation is moot.   D                    To create a detached process with a CLI, you mustD                    specify LOGINOUT as the target image as discussedE                    elsewhere in the FAQ, or only use these calls (and H                    any other calls requiring a CLI) from images that areH                    running in an "interactive", "batch", or "other" mode                    process.e  E                    Also note that the lib$spawn and the C system callhJ                    will fail in a CAPTIVE login environment. The lib$spawnJ                    call can be gotten to work in this environment with the5                    specification of the TRUSTED flag.   D           __________________________________________________________@           10.16  Where can I obtain Bliss, and the libraries and"                  supporting files?  E                    The Bliss language compilers and documentation are C                    available on the OpenVMS Freeware distributions.   I                    Bliss language source code that contains the following                     statement:   7                      LIBRARY 'SYS$LIBRARY:STARLET.L32';i  @                    or similar requires the presence of the BlissG                    libraries. These libraries are created on the targetaF                    system using the Bliss require files, and are built6                    using the following Bliss commands:  I                    STARLET.L32 contains the public interfaces to OpenVMS:   H                        $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L32 -2                            SYS$LIBRARY:STARLET.REQ  J                    LIB.L32 contains both the public and private interfaces                    to OpenVMS:  D                        $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]LIB.L32 -F                            SYS$LIBRARY:LIB.REQ+SYS$LIBRARY:STARLET.REQ                      10-14 o  g          2                    OpenVMS Programming Information        E                    The equivilent files for Bliss64 are created with:$  G                        $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]LIB.L64 -TF                            SYS$LIBRARY:LIB.R64+STARLET.REQ+STARLET.R64K                        $ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L64 -/2                            SYS$LIBRARY:STARLET.R64  C                    Some Bliss code may also require the OpenVMS VAX F                    architecture flags. The following is the equivilent5                    of the Alpha ARCH_DEFS.REQ module:i             ! A           ! This is the OpenVMS VAX version of ARCH_DEFS.REQ, andSD           ! contains the architectural definitions for conditionallyC           ! compiling OpenVMS Bliss sources for use on VAX systems.AD           ! (If you should encounter compilation errors here, please>           ! seriously consider upgrading your Bliss compiler.)           !            MACRO VAXPAGE = 1%;            MACRO BIGPAGE = 0%;i           !iE           MACRO VAX =                     ! = 1 if compiled BLISS/VAX I                   %BLISS(BLISS32V)%;      ! = 0 if not compiled BLISS/VAX   Y           MACRO EVAX =                    ! = 1 if compiled BLISS/E* (Obsolete, old name)pV                   (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn  T           MACRO ALPHA =                   ! = 1 if compiled BLISS/E* (New arch name)V                   (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn  T           MACRO IA64 =                    ! = 1 if compiled BLISS/I* (New arch name)Y                   (%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /Ann=             MACRO ADDRESSBITS =iM                   %BPADDR%;               ! = 32 or 64 based on compiler usedS  G                    Some Bliss code may require the definition files for F                    the OpenVMS older LIBRTL routine lib$tparse, or the.                    newer lib$table_parse call:  G                        $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]TPAMAC.L32 -f1                            SYS$LIBRARY:TPAMAC.REQ     J                                                                      10-15               2                    OpenVMS Programming Information      D           __________________________________________________________9           10.17  How can I open a file for shared access?t  J                    When creating a file, it is often useful to allow otherH                    applications and utilities-such as TYPE-to share readF                    access to the file. This permits you to examine the8                    contents of a log file, for instance.  I                    A C source example that demonstrates how to do this ismJ                    available in topic (2867) in the OpenVMS Ask The Wizard                    area:  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availableoF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.   F                    Depending on the environment, you may need to use CI                    calls such as fsync and fflush, and-in specific cases-d,                    the setvbuf(_IONBF) call.  A                    For related materials around commands that canoG                    potentially be used to override file locking-to view E                    the file contents as currently written to disk-see                      Section 9.12.  D           __________________________________________________________G           10.18  How can I have common sources for messages, constants?   D                    Use the GNM tools on the OpenVMS Freeware to haveB                    common sources for MSG (message) files and SDMLC                    (Document) documentation files. Use the DOCUMENTtE                    command to convert the SDML documentation into thetG                    necessary formats (Text, Postscript, HTML, etc). UsecH                    the MESSAGE/SDL tool (latent in OpenVMS) to create anH                    SDL file based on the messages. Then use the SDL toolI                    (available on the OpenVMS Freeware) to convert the SDL J                    file into language-specific definitions. (There is alsoF                    a converter around to convert SDL into SDML, if youG                    want to get pictures of the data structures for your "                    documentation.)                      10-16               2                    OpenVMS Programming Information      D           __________________________________________________________?           10.19  How do I activate the OpenVMS Debugger from ano                  application?   ,                    #include {lib$routines.h}%                    #include {ssdef.h}t&                    #include {string.h}                      main()o                        {6                        char ascic_debug_commands[128];<                        char *dbgcmd = "*show calls;go;exit";  >                        strcpy( ascic_debug_commands, dbgcmd );J                        ascic_debug_commands[0] = (char) strlen( dbgcmd ) -           1;  D                        lib$signal(SS$_DEBUG,1,ascic_debug_commands);                           return 1;                        }  H                    Also see Section 10.28 for another related discussionH                    of the OpenVMS Debugger, and of a technique that uses(                    the SS$_DEBUG signal.  D           __________________________________________________________*           10.20  Dealing with Endian-ness?  F                    OpenVMS VAX, OpenVMS Alpha and OpenVMS I64 (as wellH                    as all Microsoft Windows implementations) all supportG                    and all use the little-endian byte ordering. Certain B                    Alpha microprocessors and certain Intel ItaniumH                    processors can be configured to operate in big-endianE                    and potentially in bi-endian mode. HP-UX typically_'                    operates big-endian.   G                    With little-endian byte order, the least significantMH                    byte is always the first byte; the byte at the lowestC                    address. With big-endian byte ordering, the bytelJ                    storage order in memory is dependent on the size of theH                    data (byte, word, longword) that is being referenced.  F                    Endian-ness is a problem has been solved many times@                    before. Some of the typical solutions include@                    htonl/htons and ntohl/ntohs in the standard CE                    library and the TCP/IP Services XDR (eXternal DataeF                    Representation) libraries. One of the more recently  J                                                                      10-17    t          2                    OpenVMS Programming Information        E                    introduced network formats, and one that is seeingaB                    extensive press and marketing coverage, is XML.  D           __________________________________________________________7           10.21  How to resolve LINK-I-DATMISCH errors?(  D                    The message LINK-I-DATMISCH is informational, andH                    indicates that the version of the specified shareableF                    image found in the system shareable image directoryI                    does not match the version of the shareable image thatdF                    was originally loaded into IMAGELIB.OLB, one of theF                    OpenVMS libraries typically searched by the LINKER.  I                    From a privileged username, you can usually completely =                    repair this via the following DCL command:,  K           $ LIB/REPLACE/SHARE SYS$LIBRARY:IMAGELIB.OLB SYS$SHARE:LIBRTL.EXE   E                    This command assumes that the shareable image that H                    was found in the SYS$SHARE: area is valid and upward-I                    compatiable, and that the image has simply replaced an @                    older version without also updating IMAGELIB.  D           __________________________________________________________E           10.22  HP C and other OpenVMS C Programming Considerations?   E                    VAX C V3.2 was released for OpenVMS VAX systems in.I                    1991. DEC C V4.0 replaced VAX C V3.2 in 1993 as the HPaG                    C compiler for OpenVMS VAX systems. HP C is the ANSIrG                    C compiler for OpenVMS Alpha systems. VAX C predatesdG                    the ANSI C standards, and has various areas that are J                    not compliant with ANSI C requirements. HP C is an ANSIH                    C compiler, and can also compile most VAX C code whenI                    /STANDARD=VAXC is specified. Versions of this compiler I                    between V3.2 and V6.5 (exclusive) were known as DEC C, +                    DIGITAL C, and Compaq C.H  J                    Both compilers can be installed at the same time on theI                    same OpenVMS VAX system, allowing a migration from VAXsJ                    C to DEC C, and allowing the same DEC C code to be used4                    on OpenVMS VAX and OpenVMS Alpha.  E                    The system manager can choose the system default CiJ                    compiler when HP C is installed on a system with VAX C,H                    and a C programmer can explicitly select the required=                    compiler for a any particular compilation.h                      10-18               2                    OpenVMS Programming Information        H                    A current "C" license PAK allows access to both VAX C;                    and HP C on the same OpenVMS VAX system.   H                    Various HP C versions can be installed on OpenVMS VAXH                    V5.5-2 and later. OpenVMS VAX releases such as V5.5-2G                    and V6.0 will require the installation of a HP C RTL F                    kit, a kit that is included with the HP C compiler.G                    OpenVMS VAX versions V6.1 and later do not require a H                    seperate RTL kit, but HP C RTL ECO kits are availableF                    to resolve problems found with the C RTL on various$                    OpenVMS releases.  H                    With HP C, for automatic resolution of the standard CJ                    library routines by the LINKER utility, use the /PREFIXJ                    qualifier, such as /PREFIX=ALL_ENTRIES. If a particularE                    application program replaces an existing C library1H                    routine, use /PREFIX=(ALL_ENTRIES,EXCEPT=(...)). (VAXH                    C required explicit specification of an RTL shareable>                    image or C object library during the link.)  H                    When the /PREFIX is requested, the compiler generatesI                    a "decc$" prefix on the specified symbols. This prefixXD                    allows the LINKER to resolve the external symbolsG                    against the symbols present in the DECC$SHR library.rG                    The DECC$SHR library is included in the IMAGELIB.OLB G                    shareable image library, and IMAGELIB is searched byeH                    default when any program (written in any language) isG                    LINKed. Because the standard C library routine names H                    are very likely to match application routines writtenI                    in other languages, a prefix "decc$" is added to the C F                    symbol names to assure their uniqueness; to preventD                    symbol naming conflicts. C programs, however, canI                    sometimes have private libraries for various purposes, D                    and the external routines share the same names asF                    the library routines. (This is not recommended, butJ                    there are applications around that use this technique.)H                    Thus the need to explicity specify whether or not theE                    "decc$" prefix should be prepended to the externale0                    symbol names by the compiler.  B                    The qualifiers, and most (all?) with associatedF                    pragmas, that may be of interest when migrating VAX*                    C code to HP C include:  J                                                                      10-19 a  a          2                    OpenVMS Programming Information        D                    o  Failure to specify the prefixing qualifier (onH                       certain and usually older versions of C) can causeH                       the compiler to not add the prefixes for the namesC                       of the C library routines into the referencestD                       placed in the object module, which can in turnF                       cause problems resolving the external symbols inA                       the library when the object code is linked:r             /PREFIX=ALL_ENTRIES   I                    o  Some VAX C programs erroneously write to the stringtC                       literals. By default, HP C does not allow the *                       constants to change.  *           /ASSUME=WRITABLE_STRING_LITERALS  F                    o  Enables sharing ("shr") of globals and of externC                       variables. HP C sets externs as non-shareablel0                       ("noshr"), VAX C as "shr".             /SHARE_GLOBALS  C                    o  VAX C assumes common block model for external                        linkages.u  #           /EXTERN_MODE=COMMON_BLOCK   J                    o  Refers to the padding placed between member elementsG                       within a struct. Disabling member alignment packs A                       the data more tightly into memory, but this E                       packaging has performance implications, both on C                       OpenVMS VAX and particularly on OpenVMS AlphaO                       systems.             /[NO]MEMBER_ALIGNMENTe  G                    o  Enable all manner of useful compiler diagnostics:_  N           /WARN=ENABLE=(LEVEL4,QUESTCODE)/STANDARD=PORT/ACCEPT=NOVAXC_KEYWORDS  E                       You can disable extraneous diagnostics with thek                        following:  #                       #ifdef __DECC *                       #pragma message saveK                       #pragma message disable /* insert message tag here */o                       #endif                      10-20    O          2                    OpenVMS Programming Information        C                    Permit structure members to be naturally aligned/@                    whenever possible, and avoid using /NOMEMBER_F                    ALIGNMENT. If you need to disable member alignment,G                    use the equivilent #pragma to designate the specificaJ                    structures. The alignment of structure members normallyD                    only comes into play with specific unaligned dataD                    structures-such as the sys$creprc quota itemlist-H                    and with data structures that are using data that wasG                    organized by a system using byte or other non-memberE                    alignment.T  J                    Versions of HP C such as V6.0 include the capability toH                    extract the contents of the standard header librariesF                    into directories such as SYS$SYSROOT:[DECC$LIB...],H                    and provide various logical names that can be definedG                    to control library searches. With HP C versions suchcH                    as V6.0, the default operations of the compiler matchH                    the expectations of most OpenVMS programmers, withoutF                    requiring any definitions of site-specific library-F                    related logical names. (And logical names left fromH                    older DEC C versions can sometimes cause the compiler3                    troubles locating header files.)t  D                    HP C V5.6 and later include a backport library, aC                    mechanism by which HP C running on older OpenVMSoG                    releases can gain access to newer RTL routines addednI                    to the RTL in later OpenVMS releases-the language RTLsiH                    ship with OpenVMS itself, and not with the compilers.  C                    Example C code is available in SYS$EXAMPLES:, ineB                    DECW$EXAMPLES (when the DECwindows examples areG                    installed), in TCPIP$SERVICES (or on older releases,rJ                    UCX$EXAMPLES) when HP TCP/IP Services is installed), onA                    the Freeware CD-ROMs, and at web sites such asd  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availableLF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.   J                                                                      10-21 u             2                    OpenVMS Programming Information      '           _____________________________ (           10.22.1  Other common C issues  H                    The localtime()  function and various other functionsI                    maintain the number of years since 1900 in the "structuJ                    tm" structure member tm_year. This field will contain aI                    value of 100 in the year 2000, 101 for 2001, etc., and I                    the yearly incrementation of this field is expected to                     continue.  H                    The C epoch typically uses a longword (known as time_E                    t) to contain the number of seconds since midnightiG                    on 1-Jan-1970. At the current rate of consumption of G                    seconds, this longword is expected to overflow (when F                    interpreted as a signed longword) circa 03:14:07 onF                    19-Jan-2038 (GMT), as this time is circa 0x7FFFFFFFB                    seconds since the C base date. (The most commonE                    solution is to ensure that time_t is an unsigned.)   D                    If C does not correctly handle the display of theF                    local system time, then check the UTC configurationJ                    on OpenVMS-the most common symptom of this is a skew ofG                    one hour (or whatever the local daylight saving time4I                    change might be). This skew can be caused by incorrectFF                    handling of the "is_dst" setting in the applicationH                    program, or by an incorrect OpenVMS UTC configurationB                    on the local system. (See section Section 4.4.)  G                    Floating point is prohibited in OpenVMS Alpha inner- F                    mode (privileged) code, and in any process or otherF                    execution context that does not have floating pointE                    enabled. C programmers developing and working withoI                    OpenVMS Alpha high-IPL kernel-mode code such as deviceiI                    drivers will want to become familiar with the floatingnJ                    point processing available in the environment, and withJ                    the C compiler qualifier /INSTRUCTION_SET=[NO]FLOATING_H                    POINT. Device drivers and other similar kernel-mode CH                    code must be compiled with /INSTRUCTION_SET=FLOATING_9                    POINT and /EXTERN_MODEL=STRICT_REFDEF.o  F                    Additionally, the SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARYH                    parameter will be needed to be appended to the moduleI                    specification or declared via the C compiler's include H                    library logical name mechanism when the C compiler isI                    resolving kernel-mode data structures and definitions.oF                    This library contains OpenVMS kernel-mode and other                      10-22 T  d          2                    OpenVMS Programming Information        C                    system declaractions, and particularly a mixture D                    of undocumented definitions and declarations, andE                    particularly definitions and declarations that areyF                    subject to change (and that can accordingly lead toD                    requirements for the recompilation of application                    code).V  H                    In addition to the user-mode C Run-Time Library (RTL)C                    mentioned in the OpenVMS C RTL documentation and H                    referenced over in Section 3.9, there is a second andH                    parallel kernel-mode RTL accessable to device driversE                    and other kernel code on OpenVMS Alpha and OpenVMSbE                    I64. The most common time this second C library isqF                    noticed is when C code is (erroneously) linked withH                    /SYSEXE/SYSLIB, and duplicate symbol errors typicallyI                    then arise. As code running in supervisor-, executive- E                    or kernel-mode context cannot call out a user-modedC                    RTL or other user-mode library, you will want toiG                    respecify the command as LINK /SYSEXE/NOSYSLIB. ThisMI                    will eliminate the duplicate symbol errors, since only J                    the kernel-mode library will be referenced, and it willG                    also avoid calling out into the user-mode libraries.   G                    When sharing variables with other languages, here is ,                    some example HP C code...                            ...2                          #pragma extern_model save;                          #pragma extern_model strict_refdefE4                          extern int   VMS$GL_FLAVOR;5                          #pragma extern_model restore                           ...  D                    and here is some associated example Bliss code...                            ...!                          EXTERNAL *                             VMS$GL_FLAVOR,                          ....P          J                                                                      10-23    e          2                    OpenVMS Programming Information      '           _____________________________F*           10.22.2  Other common C++ issues  B                    HP C++ (a separate compiler from HP C) providesC                    both symbol mangling and symbol decoration. Some E                    of the details of working with longer symbol names B                    and the resulting symbol name mangling in mixedD                    language environments are listed in the shareableG                    image cookbook, and in the C++ documentation. Symbol G                    name decoration permits the overloading of functionsmC                    (by adding characters to the external symbol for D                    the function to indicate the function return typeD                    and the argument data types involved), and mixed-H                    language external references can and often do need toI                    disable this decoration via the extern "C" declaratione                    mechanism:c  #                          extern "C"S                            {;                            extern int ExternSymbol(void *); @                            extern int OtherExternSymbol(void *);                            }  I                    Also see Section 14.7 for information on /ARCHITECTUREp&                    and /OPTIMIZE=TUNE.  H                    See Section 10.15 for information on the C system and>                    the lib$spawn call in CAPTIVE environments.  D                    Constructs such as the order of incrementation orF                    decrementation and the order of argument processingJ                    within an argument list are all implementation-defined.?                    This means that C coding constructs such as:                           i = i++;C"                        a[i] = i++;)                        foo( i, i++, --i);c  I                    are undefined and can have (adverse) implications whenaI                    porting the C code to another C compiler or to anotherhI                    platform. In general, any combination of ++, -, =, +=,eJ                    -=, *=, etc operators that will cause the same value toJ                    be modified multiple times (between what the ANSI/ISO CJ                    standard calls "sequence points") produce undefined and3                    implementation-specific results.c                      10-24 f  d          2                    OpenVMS Programming Information        E                    Within C, the following are the "sequence points":aF                    the ";" at the end of a C statment, the ||, &&, ?:,F                    and comma operators, and a call to a function. NoteH                    specifically that = is NOT a sequence point, and thatG                    the individual arguments contained within a function J                    argument list can be processed from right to left, from8                    left to right, or at any random whim.  E                    HP C for OpenVMS VAX (formerly DEC C) and VAX C don4                    differ in the related processing.  F                    So you are looking for OpenVMS-specific definitions#                    (include files)?   @                    UCBDEF.H, PCBDEF.H and other OpenVMS-specificG                    definitions-these are considered part of OpenVMS and F                    not part of the C compiler kit-are available on all1                    recent OpenVMS Alpha releases.m  D                    To reference the version-dependent symbol libraryH                    sys$share:sys$lib_c.tlb, use a command similar to the-                    following for compilation:f  9                    $ CC sourcea+SYS$LIBRARY:SYS$LIB_C/LIB   I                    You can also define DECC$TEXT_LIBRARY to reference the                     library.e  C                    You will want to review the Programming Concepts H                    manual, and specifically take a quick look at Chapter                    21.  G                    And some general background: the STARLET definitionssG                    (and thus the sys$starlet_c.tlb library) contain theoF                    symbols and the definitions that are independent ofE                    the OpenVMS version. The LIB definitions (and thusYF                    sys$lib_c) contain symbols and definitions that canI                    be dependent on the OpenVMS version. You won't need to,I                    rebuild your code after an OpenVMS upgrade if you have H                    included definitions from STARLET. The same cannot beI                    said for some of the definitions in LIB-you might need G                    to rebuild your code. (The UCB structure can and has B                    changed from release to release, for instance.)  I                    Recent versions of C automatically search sys$starlet_ D                    c.tlb. Explicit specification of sys$lib_c.tlb is                    required.  J                                                                      10-25 n  r          2                    OpenVMS Programming Information        E                    Also see the Ask The Wizard website topics (2486),r&                    (3803), and (1661):  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the available F                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.d  A                    See Section 9.5 for information on the C off_t/H                    limitations, resolved in OpenVMS V7.3-1 and later andG                    in ECO kits available for specific OpenVMS releases.rI                    The use of a longword for off_t restricts applicationszG                    using native C I/O to file sizes of two gigabytes or I                    less, or these applications must use native RMS or XQPo1                    calls for specific operations.   D           __________________________________________________________<           10.23  Status of Programming Tools on OpenVMS VAX?  G                    DECthreads V7.3 and the HP C compiler (also known aseE                    Compaq C and DEC C) V6.4 are presently expected tooE                    be the last updates and the last releases of thesefH                    development packages for use on OpenVMS VAX. The run-G                    time support for both DECthreads (CMA$RTL) and for CpG                    (DECC$CRTL) will continue to be maintained, and will_E                    continue to be available on OpenVMS VAX. The VAX C H                    V3.2 compiler is the final VAX C compiler release forH                    OpenVMS VAX, and the VAX C Run-Time Library (VAXCRTL)6                    will also continue to be available.  ?                    New development and new features and productOF                    enhancements continue for the OpenVMS Alpha and the<                    OpenVMS IA-64 DECthreads and C compilers.                                10-26               2                    OpenVMS Programming Information      D           __________________________________________________________@           10.24  Choosing a Version Number for Application Code?  G                    One of the common rules-of-thumb used for choosing a I                    displayed version number string for a new version of ahG                    layered product or an application, its implications,VF                    and its expected effects on client applications and"                    users, follows:  G                    o  No functional and no application-visible changes,_C                       bugfixes only-the edit number is incremented.sI                       These tend to be very small, very isolated, or ECO-lH                       level changes. These can also be distributions forG                       specific hardware configurations or platforms, as J                       is the case with an OpenVMS Limited Hardware ReleaseG                       (LHR). Application rebuilds are not expected, and G                       there is an assumption that general user-provided H                       application-related regression testing will not be                       required.r  B                    o  Minimal functional and very few user-visibleJ                       changes-the maintenance number is incremented. TheseF                       tend to be very small or even ECO-level changes,G                       though somewhat larger than an edit-level change.iI                       Application rebuilds are not expected, and there issJ                       an assumption that user-provided application-related>                       regression testing will not be required.  D                    o  Various small and upward-compatible functionalF                       changes-the minor version number is incremented.J                       The changes are user-visible, and are intended to beJ                       user-visible. Application rebuilds are not expected.H                       Some application programmers may choose to perform'                       regression tests.h  D                    o  Large and/or potentially incompatible changes-C                       the major version number is incremented. SomenD                       applications might need to be rebuilt. VariousD                       application programmers will choose to performH                       regression tests of their respective applications.  E                    For additional version-numbering materials and foriF                    information on assigning module generation numbers,G                    please see the OpenVMS (POLYCENTER) Software Product H                    Installation Utility-variously refered to by acronyms  J                                                                      10-27               2                    OpenVMS Programming Information        E                    including PCSI and SPIA-reference manual available 8                    within the OpenVMS documentation set.  A                    Of course, all of this is obviously subject to F                    interpretation, particularly around the distinctionF                    between large and small changes and such. The scaleE                    of the application is also a factor, as larger and E                    more complex applications will tend toward smallermI                    increments and will tend to see the maintenance numbernJ                    incremented, while new releases of smaller applicationsJ                    will tend to see the minor version incremented somewhat#                    more frequently.i  I                    The goal of all this is to provide a guide to relativeaF                    scale of changes and the associated effort involvedH                    in an upgrade for the user and/or for the application                    programmer.  D           __________________________________________________________4           10.25  Selecting a Process Dump Directory?  E                    You can customize the device and directory for thenI                    process dump by defining the logical names SYS$PROCDMP D                    and SYS$PROTECTED_PROCDMP. The former is for non-E                    privileged dumps, while the latter is the location @                    where privileged image dumps are written, andI                    preferably an area protected against untrusted access._                    For example:   5                    $ define SYS$PROCDMP SYS$ERRORLOG: E                    $ define /exec SYS$PROTECTED_PROCDMP SYS$ERRORLOG:   I                    The abouve presumes that the SYS$ERRORLOG logical name .                    points to a valid location.  H                    There is presently no means to change the name of theF                    generated dump file from IMAGENAME.DMP to somethingD                    else. Accordingly, you will want to use differentD                    target directories for this purpose, particularlyC                    if there is more than one application or processT5                    potentially writing process dumps.a                          10-28 G  g          2                    OpenVMS Programming Information      D           __________________________________________________________-           10.26  Access to Itanium Assembler?N  @                    If you are interested in accessing the nativeE                    Intel Itanium assembler within the OpenVMS I64 GNVpG                    environment-and since the iasi64 assembler is a UnixaI                    program and GNV is a Unix environment for OpenVMS I64- E                    you can simply copy iasi64.ext into your gnu:[bin]V@                    directory in place of "as.", and of "AS.EXE".  I                    Alternately and probably also better, you can write anmG                    "as." script to invoke the iasi64.exe image from itseD                    particular prefered location on the local system.  :                    A typical "as." script looks like this:  1                    path/iasi64.exe $1 $2 $3 $4 $5   D           __________________________________________________________1           10.27  Kernel-mode coding restrictions?   G                    Floating point is prohibited in OpenVMS Alpha inner-tJ                    mode (privileged) code, and within any process or otherF                    execution context that does not have floating point)                    enabled and available.s  H                    Programmers developing and working with OpenVMS AlphaE                    high-IPL kernel-mode code, such as device drivers,_J                    will further want to become familiar with the floating-E                    point processing and the instruction set emulation E                    available in the particular target environment (ifdI                    any). When working with C, inner-mode programmers willsH                    want to become familiar with the C compiler qualifier7                    /INSTRUCTION_SET=[NO]FLOATING_POINT.O  F                    Device drivers and other similar kernel-mode C codeH                    must be compiled with /INSTRUCTION_SET=FLOATING_POINT3                    and /EXTERN_MODEL=STRICT_REFDEF.   G                    Additionally, inner-mode code cannot call out to thelF                    user-mode language run-time libraries nor to any ofH                    the OpenVMS system run-time libraries. In particular,J                    this prohibition prevents pages of inner-mode-protectedJ                    memory from being allocated and interspersed within theJ                    user-mode heap or other such user-mode data structures.  J                                                                      10-29    A          2                    OpenVMS Programming Information        H                    The prohibtion on user libraries also generally meansI                    that such code must be linked with LINK /NOSYSLIB, andtF                    quite probably also with /SYSEXE. The former causesE                    the linker to avoid searching the system shareable G                    image libraries (via IMAGELIB.OLB), while the latter I                    brings in symbols typically only known to or otherwise 9                    accessable from the OpenVMS executuve.n  D                    To include kernel-mode C programming definitions,F                    macros and system constants within a C compilation,E                    include SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY on the CeE                    compilation. (Constructs defined within the systemsC                    macro library LIB.MLB or within its C equivalent,A                    SYS$LIB_C.TLB tend to be version-dependent, oro?                    undocumented, or both.) As an example of theeJ                    compilation, the following is a typical C device driver'                    compilation command:o  V           $   CC /STANDARD=RELAXED_ANSI89/INSTRUCTION=NOFLOATING_POINT/EXTERN=STRICT -P                   'DEBUG_CC_DQ_OPT' 'ARCH_CC_OPT' 'CHECK_CC_OPT' 'SHOW_CC_OPT' -E                   /LIS=LIS$:xxDRIVER/MACHINE_CODE/OBJ=OBJ$:xxDRIVER -iC                   SRC$:xxDRIVER.C+SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY-  I                    Additionally, code running in executive mode in an ASThJ                    or in kernel mode cannot call RMS services, or routines9                    which directly or indirectly call RMS.   D                    For related kernel-mode programming materials andG                    driver documentation, please see the Writing OpenVMSWE                    Alpha Device Driversin C book, ISBN 1-55558-133-1.x  D           __________________________________________________________=           10.28  Decoding an Access Violation (ACCVIO) Error?e  H                    To decode the virtual addresses returned by an accessG                    violation or by another similar OpenVMS display, youaE                    need to have created and retained a listings file-rJ                    preferably one with machine code generation enabled-and#                    a full link map.c  D                    Starting with the virtual address reported by theB                    error, use the link map to find the module thatI                    contributed the code that contains the virtual addressrJ                    range. Calculate the offset from the base of the range,H                    by subtracting the base of the range from teh failingF                    virtual address. Then use the compiler listings for                      10-30 d  d          2                    OpenVMS Programming Information        H                    the particular component that contributed the code to@                    locate the offset of the failing instruction.  J                    If the map and listings information was not maintained,J                    working backwards is far more difficult-you are left toH                    use the binary instruction data around the failure toI                    locate the associated source code, and this process is G                    far more involved. This usually involves matching up J                    blocks of decoded instructions around the failing code,G                    or the direct analog involving matching up ranges of H                    decoded instructions. Keep the maps and listing files*                    around, in other words.  J                    Rather easier than an approach based on virtual addressH                    arithmetic and far easier than working backwards fromI                    the instruction stream is to use integrated debugging-lG                    this inclusion is arguably an essential component ofdE                    any non-trivial application-and to use the OpenVMSa                    Debugger.  D                    The OpenVMS Debugger in particular can be used toI                    examine the source code, to examine the stack, and canaI                    even be programmed to wait patiently for the incidenceaE                    of a particular value or failure or condition, andnE                    this is far easier than working backwards from thesE                    instruction stream is to use integrated debugging-tG                    this inclusion is arguably an essential component of E                    any non-trivial application-and to use the OpenVMS D                    Debugger. The debugger can also be activated fromD                    within a signal handler, and commands to generateD                    a traceback can be generated directly, or throughG                    the invocation of a procedure containing a series ofs%                    debugger commands.i  F                    Details on the debugger are in the OpenVMS DebuggerE                    Manual, and also see the discussion of dyanmicallyt<                    activating the Debugger in Section 10.19.              J                                                                      10-31 r  n          2                    OpenVMS Programming Information      D           __________________________________________________________0           10.29  Generating an AUTODIN-II CRC32?  I                    The following code can be used to generate an AUTODIN-pJ                    II 32-bit Cyclic Redundency Check (CRC32) value from anJ                    input string descriptor, similar to that used by the HPH                    C compiler for its /NAMES=SHORTENED mechanism, and by@                    various other applications requiring a CRC32.  H                    The routine uses the OpenVMS library routine lib$crc_J                    table to generate a sixteen longword array of data fromI                    the specified encoded polynomial coefficient (AUTODIN- F                    II, in this case), and then lib$crc to generate theA                    CRC32 value from the array and the input data.h  H           static int CreateCRC32( struct dsc$descriptor *InputDataDesc )
             {              uint32 AUTODIN2;             uint32 Seed = ~0UL; /             uint32 Coefficient = 0x0EDB88320UL;o              uint32 CRCArray[16];  ,             lib$establish( lib$sig_to_ret );  F             lib$crc_table( (void *) &Coefficient, (void *) CRCArray );S             AUTODIN2 = lib$crc( (void *) CRCArray, (void *) &Seed, InputDataDesc );              AUTODIN2 ^= Seed;o               return AUTODIN2;
             }t  D           __________________________________________________________+           10.30  Enabling built-in tracing?   *                    $ RUN SYS$SYSTEM:SYSMAN?                    SYSMAN> SYS_LOAD ADD TR$DEBUG TR$DEBUG/LOAD_            STEP=INIT/LOGl                    SYSMAN> Exiti6                    $ @SYS$UPDATE:VMS$SYSTEM_IMAGES.COM  8                    To stop it from loading early in boot  +                    $  RUN SYS$SYSTEM:SYSMAN2@                    SYSMAN> SYS_LOAD REMOVE TR$DEBUG TR$DEBUG/LOG                    SYSMAN> Exit_6                    $ @SYS$UPDATE:VMS$SYSTEM_IMAGES.COM                      10-32               2                    OpenVMS Programming Information        F                    The first occurance of the name TR$DEBUG within theE                    command is considered the "product" and the second E                    is considered the "image" that should exist within '                    SYS$LOADABLE_IMAGES.   A                    When TR$DEBUG loads in the init phase, it will 1                    automatically turn on tracing.P  1                    Also see the SDA TR extension.2                                                                      J                                                                      10-33 e                       J                    _______________________________________________________             11       DECwindowsi      D           __________________________________________________________A           11.1  How do I let someone else display something on mya                 workstation?  I                    On a workstation, you will want to use the "Customize" A                    menu of the session manager utility and select C                    "Security". When the pop-up box appears, you can I                    select the host node, username, and tranport that will_F                    allow you to launch an application that targets the'                    workstation display._  B                    If this does not provide you with access to the:                    display, You need a checklist of sorts:  C                    o  Make sure that you've specified the X-windows C                       "display" correctly on the remote host. For a J                       DECnet transport, the specification uses two colons,H                       while the TCP/IP transport typically uses one. TheF                       X Windows server and the X Windows screen followH                       the host specification, delimited by a period. For                       example:  J           ________________________________________________________________0           Table 11-1  X Windows Display Commands  J                    _______________________________________________________J                    Shell_____Command______________________________________                      csh  <                              # setenv DISPLAY vms.domain:0.0                      sh and kshw  H                              # $ DISPLAY=vms.domain:0.0 ; export DISPLAY                      DCL  C                              $ SET DISPLAY/CREATE/NODE=vms.domain -_J           ___________________/TRANSPORT=TCPIP/SERVER=server/SCREEN=screen_  E                    o  If you have verified the command is correct and G                       things are still not working, ensure the Security F                       settings on the OpenVMS host side will allow the  J                                                                       11-1 S  Y                              DECwindows         G                       incoming connection: Pull down the "Options" menumJ                       in the Session Manager, and select "Security...". IfJ                       you do not find your host and username and transportI                       listed among the authorized users, you will need tot#                       add an entry.   I                      o  There are various transports available, including F                         LOCAL, DECNET, LAT, and TCPIP. You must SelectA                         the transport appropriate to the incomingP#                         connection.   D                      o  If the transport is "DECnet", do NOT add the;                         double colon (::) to the node name.t  D                      o  If the transport is "TCPIP", "Username" mustG                         be an asterisk (*). Why? Because unlike DECnet, G                         the TCP/IP protocol does not provide the remote H                         username information in the incoming connection.  G                      o  If the connection is "TCPIP", it is best to usenC                         a full domain name (e.g. Node.Subd.Domain).NC                         However, you may have to use the IP addresseC                         itself, if your host does not have a way to D                         resolve the address via DNS. If you have theH                         luxury of fixed addresses (eg: you are not usingH                         DHCP), then it can be helpful to add two entriesI                         for each TCP/IP host, one that specifies the hosttE                         name and one that specifies the host address.m  F                      o  There are various TCP/IP packages for OpenVMS,B                         and you must use syntax appropriate to the,                         transport installed.  D                      o  If a TCP/IP connection is still not working,C                         ensure that the transport you want has beent>                         activated for use with DECwindows. SeeG                         Section 11.14 for details of configuring TCP/IPa'                         as a transport.s  G                    o  There is a log file created in SYS$MANAGER: which,C                       can tell you which transports are loaded, and H                       also tell you what connect attempts were rejected,F                       including showing what the presented credentialsC                       were. This file is SYS$MANAGER:DECW$SERVER_0_iG                       ERROR.LOG, although the 0 could be another number H                       if you have multiple servers on the workstation. I                      11-2  r  s                              DECwindows,        I                       have found this file to be very useful for tracking F                       down what needs to be put in the Session Manager'                       Security entries.e  D           __________________________________________________________A           11.2  How do I create a display on another workstation?o  I                    To create a display from an OpenVMS host to a remote X J                    Windows display, use one of the following DCL commands:  S                    $ SET DISPLAY /CREATE /TRANSPORT=net_transport /NODE=remote_nodefI                    $ SET DISPLAY /CREATE /TRANSPORT=LAT /NODE=remote_nodesL                    $ SET DISPLAY /CREATE /TRANSPORT=DECnet /NODE=remote_nodeK                    $ SET DISPLAY /CREATE /TRANSPORT=TCPIP /NODE=remote_nodee  J                    Note that LAT is typically used only for the VXT seriesD                    X Windows terminals, but it can also be used fromJ                    OpenVMS to OpenVMS systems on various OpenVMS releases,J                    such as on OpenVMS Alpha V6.1 and later. For details onG                    configuring the TCP/IP transport, see Section 11.14.   H                    If you are interested in X Windows terminals and haveH                    an older VAXstation system around, please see the EWS,                    package on Freeware V5.0.  D           __________________________________________________________F           11.3  How can I get the information from SHOW DISPLAY into a                 symbol?   E                    Use the undocumented SHOW DISPLAY/SYMBOL, and then I                    reference the symbols DECW$DISPLAY_NODE, DECW$DISPLAY_ C                    SCREEN, DECW$DISPLAY_SERVER and/or DECW$DISPLAY_a                    TRANSPORT.   A                    An example of calling the underlying (and alsoaF                    undocumented) sys$qio programming interface for the4                    WSDRIVER (WSAn:) is available at:  9                    http://www.hp.com/go/openvms/freeware/l  H           Look in the Freeware V4.0 directory /srh_examples/DECUS_UNDOC_           CLINIC/.    J                                                                       11-3 ,  C                              DECwindows       D           __________________________________________________________8           11.4  How do I get a log of a DECterm session?  H                    If you are working from a DECwindows DECterm terminalF                    emulator, you can use the AutoPrint feature. ChooseJ                    the "Printer..." menu item from the "Options" menu, setG                    the printing destination to the name of the file you G                    want, and set "Auto Print Mode". You are now free toi                    continue.  D                    It should be noted that all of the characters andH                    escape sequences are captured, but if you display theE                    resulting log file on a DECterm, then you will seey9                    exactly what was originally displayed.   E                    You can also use the "Print Screen" screen capture H                    available in the DECwindows session manager menus, ifJ                    you simply wish to snapshot a particular portion of the%                    X Windows display.u  I                    If you are using the Freeware VTstar terminal emulatoreH                    package, you will find a similar logging mechanism is*                    available in the menus.  D           __________________________________________________________5           11.5  Why is DECwindows Motif not starting?   D                    First check to see if there is a graphics device,E                    usually a G* device. (eg: On a DEC 2000 model 300,fG                    use the command SHOW DEVICE GQ) If you do not find a #                    graphics device:l  D                    o  OpenVMS has failed to find the appropriate IRQC                       information for an EISA graphics card (on the G                       DEC 2000 series) such as the HP (Compaq) QVision,5G                       and did not autoconfigure it. Run the correct ECUkF                       (for Tru64 UNIX and OpenVMS) and reboot. This is;                       necessary only on EISA-based systems.e  D                    o  You have an EISA-based system (such as the DECC                       2000 model 300) and do not have a HP (Compaq)tH                       QVision video card. This EISA graphics card shouldF                       have Compaq printed on it, and identifies itselfD                       as a CPQ3011 or a CPQ3111. If it is not one ofC                       these two EISA devices, then OpenVMS does notMD                       support it. (There are no other supported EISAJ                       graphics controllers, and EISA graphics are normally                      11-4     0                              DECwindowsq        F                       used with DECwindows only on the DEC 2000 series                       systems.)r  D                    o  You have a PCI-based system, and do not have aI                       supported graphics controller-examples of supportedc8                       controllers include the following:  #                      o  Radeon 7500   8                      o  PowerStorm 3D30, PowerStorm 4D20  )                      o  3DLabs Oxygen VX1   I                       See Section 5.16 for further information on some of 1                       these graphics controllers.   C                    o  You have booted the system minimally, or havebE                       otherwise disabled the device autoconfigurations                       process.  <                    If there is a G* graphics device present:  ?                    o  There may have been a severe error in thee>                       DECwindows startup. Type the contents ofA                       SYS$MANAGER:DECW$SERVER_0_ERROR.LOG for anyf@                       information on errors starting the server.  F                    o  The system parameter WINDOW_SYSTEM is not set toH                       1. While this was a common way for system managersE                       to disable the DECwindows server startup, it isGE                       not particularly reliable as DECwindows can now -                       "correct" this setting.E  F                       If you really do not want an OpenVMS system withE                       workstation hardware to bootstrap and configuree@                       itself as a workstation, add the following3                       definition to SYLOGICALS.COM:   G                       $ DEFINE/SYSTEM/EXEC DECW$IGNORE_WORKSTATION TRUE   G                    o  You may not have a valid DECwindows Motif licenseoG                       loaded. To check for the two most common types ofrF                       Motif product authorization keys (PAKs), use the-                       following DCL commands:o  2                       $ LICENSE LIST DW-MOTIF/FULL6                       $ LICENSE LIST NET-APP-SUP*/FULL  J                                                                       11-5    E                              DECwindowsT        F                       and examine the information displayed. Make sureF                       that one of these licenses is present, valid and                       active.   E                       For information on registering software licensen@                       product authorization keys (PAKs) when youE                       cannot log into the system directly, please see $                       Section 5.6.2.  E                    o  Check that the DECW$PRIVATE_SERVER_SETUP.COM isdE                       correct for the graphics controller in use. Fore                       instance:   E                       The following is from the 9FX Vision 330 Owners G                       Guide, EK-V330G-OG pg 2-9. Place the following in H                       DECW$PRIVATE_SERVER_SETUP.COM, creatibng .COM fromF                       .TEMPLATE if necessary. Locate the DECW$PRIVATE_G                       SERVER_SETUP.COM file in SYS$SPECIFIC:[SYSMGR] ortG                       in SYS$COMMON:[SYSMGR] as appropriate; the former C                       file is used for this system within a cluster C                       configuration, and the latter is used for allnH                       systems that do not also have a local copy of this4                       file in SYS$SPECIFIC:[SYSMGR].  6                       $ DECW$XSIZE_IN_PIXELS == xvalue6                       $ DECW$YSIZE_IN_PIXELS == yvalueI                       $ DEFINE/SYSTEM DECW$SERVER_REFRESH_RATE rate_in_Hz   G                       Also see Section 11.11. Details of the PowerStorm I                       3D30 and 4D20 settings are available in the OpenVMSf*                       Ask The Wizard area.  D           __________________________________________________________;           11.6  How do I set the title on a DECterm window?   B                    If you are creating a new DECterm window, check  =                    $ HELP CREATE /TERMINAL /WINDOW_ATTRIBUTESI  I                    If you want to change the title of an existing window,sJ                    use the following control sequences, where <esc> is theJ                    ANSI escape code, value decimal 27, and "text label" is,                    what you want to display:  G                    To set the DECterm title, send the escape character,tJ                    then the characters "]21;", then the text label string,G                    and then an escape character followed by a backslashA                    character.                       11-6t e                                 DECwindowsu        I                    To set the icon label, send the escape character, thenaE                    the characters "]2L;", then the icon label string, G                    and then an escape character followed by a backslash                     character.   E                    To set both the DECterm title and icon to the full G                    device name, you can use the following DCL commands:              $  esc[0,7] = 27O           $  fulldevnam = F$Edit(F$GetDVI("TT","FULLDEVNAM"),"UPCASE,COLLAPSE") B           $  write sys$output esc+ "]21;" + fulldevnam + esc + "\"B           $  write sys$output esc+ "]2L;" + fulldevnam + esc + "\"  G                    You can also change the title and the icon using thea*                    Options-Window... menu.  :                    Also see Section 12.1 and Section 8.13.  D           __________________________________________________________J           11.7  How do I customize DECwindows, including the login screen?  H                    To customize various DECwindows Motif characteristicsJ                    including the defaults used by the SET DISPLAY command,H                    the DECwindows login screen background logo used (theG                    default is the DIGITAL, Compaq, or HP logo), variousnH                    keymaps (also see Section 11.7.2 and Section 11.7.1),C                    the FileView defaults, session manager defaults, G                    the DECwindows login processing, DECwindows log file G                    processing, and various other DECwindows attributes, (                    see the example file:  A                    $ SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.TEMPLATEi  I                    This example template file is typically copied over to,E                    the filename SYS$COMMON:[SYSMGR]DECW$PRIVATE_APPS_cD                    SETUP.COM and then modified to meet site-specific                     requirements.  I                    Additionally, various X tools such as xsetroot, bitmap G                    and xrdb-some these can be useful in customizing the J                    appearance of an application or of the DECwindows Motif@                    display-are provided in the DECW$UTILS: area.  D                    When using DECwindows V1.2-4 and later on OpenVMSC                    Alpha, the default desktop is the Common DesktopCC                    Environment (CDE). You can select your preferredeE                    desktop (CDE or DECwindows Motif) when logging in,rB                    or you can change the default to the DECwindows  J                                                                       11-7 w  o                              DECwindowsp        E                    Motif desktop using the DCL symbol decw$start_new_.F                    desktop in the DECwindows private application setupH                    command procedure. See SYS$MANAGER:DECW$PRIVATE_APPS_H                    SETUP.TEMPLATE for further details, and how to create/                    DECW$PRIVATE_APPS_SETUP.COM.h  D                    Note that with DECwindows CDE, the root window isC                    no longer visible by default. The root window is E                    hidden behind the "backdrop" window of the currenteJ                    CDE workspace. To make the root window visible, use theG                    CDE style manager selection "backdrop none", and useAI                    information such as that in the OpenVMS FAQ to set thea                    root window.   >                    To add a new backdrop to the DECwindows CDEC                    environment, the backdrop must first be in or beoE                    converted into X11 pixmap format. (This conversion F                    is often possible using tools such as xv.) Then (ifC                    necessary) create the default backdrop directoryCF                    SYS$COMMON:[CDE$DEFAULTS.USER.BACKDROPS]. Place theH                    X11 pixmap file containing the desired image into theE                    backdrops directory, ensure that it has a filenamewG                    extension of .PM. (The xv default filename extension E                    for the X11 pixmap file is .XPM, while CDE expectseH                    only to see files with .PM.) Now invoke the CDE styleC                    manager and select a new backdrop. You will findtF                    your image will be placed at the end of the list of'                    backdrops available.c  F                    If you require a message be included on the initialG                    display-where the start session display and the logo(J                    appears-you can use either of the following approaches:  F                    o  The simplest approach requires OpenVMS V7.3-2 orC                       later, and the corresponding DECwindows V1.3- D                       1 kit or later. You will want to create a fileG                       named SYS$COMMON:[SYSMGR]DECW$GREET.TXT, and thiscE                       will be displayed in a popup-with an OK button-iG                       when the login box is displayed. This is intendedgD                       specifically for applications requiring such a                       display.                          11-8s e  S                              DECwindowsa        C                    o  The second approach involves copying the file )                       XRESOURCES.DAT from   M                       SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.SYSTEM.CONFIG.C]              into the directory  K                       SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.USER.CONFIG.C]   E           and editing the copy. Specifically, look for the following:n  3                       Dtlogin*greeting.labelString:   H                       The line is normally commented out, and by default*                       contains the string:  ,                       Welcome to %localhost%  G                       You can change this text to something akin to the$                        following:  <           Dtlogin*greeting.labelString:  Welcome to Heck \n\L           This is a Trusted System owned by the Rulers of the planet Zark\n\
           \n\k           We Come In Peace\n\            \n@           If you want Privacy, you've come to the wrong place\n\           \n  A                       The lines of text will be centered for you.:  F                       In most DECwindows versions, you will be able toI                       onbtain only about eight (8) lines of text. ChangesoH                       have been implemented in DECwindows V1.3 and laterG                       that permit up to about twenty-five (25) lines of\                       text.   I                    The login logo is stored as an XPM bitmap image in theeg                    text file SYS$SYSROOT:[SYSCOMMON.CDE$DEFAULTS.SYSTEM.APPCONFIG.ICONS.C]DECDTLOGO.PM,:                    and it can be changed. Copy the file to SYS$SYSROOT:[SYSCOMMON.CDE$DEFAULTS.USER.APPCONFIG.ICONS.C]DECDTLOGO.PM,oH                    as DECwindows upgrades can replace the system version                     of this file.  I                    On DECwindows V1.3-1 and later (and possibly on V1.3), H                    both DECwindows CDE and DECwindows Motif displays useI                    this logo file. On older releases, only the DECwindowsLC                    CDE displays used this logo file, while the logo G                    used for the Motif login display was hard-coded into.E                    the package and the only available override is thea  J                                                                       11-9                                   DECwindowsp        H                    DECW$LOGINLOGO command procedure mechanism within theH                    customized, site-specific DECW$PRIVATE_APPS_SETUP.COM                    file.  G                    Look at the contents of the DECDTLOGO.PM file and at F                    other *.XPM files and tools for additional details.  '           _____________________________i;           11.7.1  How do I customize DECwindows keymapping?   J                    Various keymaps can be implemented on OpenVMS and otherD                    X Windows systems, allowing the implementation ofE                    a Dvorak-style or other alternate keymappings. ForPE                    details, see the available X Windows documentationeG                    (this is the documentation associated with X WindowsMD                    itself, and not the product documentation for theB                    OpenVMS operating system nor for the DECwindowsC                    X Windows implementation) and see the DECwindowsOA                    *.DECW$KEYMAP (text-format) files found in thee5                    DECwindows DECW$KEYMAP: directory.r  H                    For other keymapping information, see Section 11.7.2.  '           _____________________________ C           11.7.2  Why does the DELETE key delete forward instead of                    backward?e  J                    Some operating systems use <Ctrl/H> as <Delete>; as theH                    character back-delete key. Most OpenVMS applications,I                    VT-series terminals (check the terminal settings, manydF                    can have this configured within the terminal set-upH                    menus), and DECterm terminals all use <Delete> as theJ                    character back-delete, and use <Ctrl/H> as a request to=                    move to the beginning of the command line.   A                    The Integrity EFI console does use <Ctrl/H> as >                    <Delete>; as the character back-delete key.  H                    Also see the SET TERMINAL/BACKSPACE command available-                    on OpenVMS V8.2 and later.h  J                    This behaviour involves the Motif virtual key bindings.J                    When a Motif application starts, it looks at the vendorH                    string returned in the display connection informationI                    and attempts to match the string to a table of virtuald                    bindings.                      11-10 r  e                              DECwindowsA        @                    You can override the default bindings in yourG                    decw$xdefaults.dat file. Here is the entry you wouldt<                    make to get the default OpenVMS bindings.  ,                    *defaultVirtualBindings:\*                     osfCancel :  <F11> \n\)                     osfLeft :  <Left> \n\ &                     osfUp  :  <Up> \n\+                     osfRight :  <Right> \n\g)                     osfDown :  <Down> \n\ 0                     osfEndLine :Alt  <Right> \n\1                     osfBeginLine :Alt  <Left> \n\s,                     osfPageUp :  <Prior> \n\-                     osfPageDown :  <Next> \n\ 2                     osfDelete :Shift  <Delete> \n\.                     osfUndo :Alt  <Delete> \n\0                     osfBackSpace :  <Delete> \n\/                     osfAddMode :Shift  <F8> \n\ )                     osfHelp :  <Help> \n\ '                     osfMenu :  <F4> \n\ +                     osfMenuBar :  <F10> \n\ -                     osfSelect :  <Select> \n\ 1                     osfActivate :  <KP_Enter> \n\ 1                     osfCopy :Shift  <DRemove> \n\ ,                     osfCut  :  <DRemove> \n\(                     osfPaste :  <Insert>                      To merge:  2                    $ xrdb :== $decw$utils:xrdb.exe:                    $ xrdb -nocpp -merge decw$xdefaults.dat  F                    Also note that the DECW$UTILS:DECW$DEFINE_UTILS.COMH                    procedure can be used to establish the xrdb and other                    symbols.   G                    Also see the DECxterm directory of Freeware V5.0 forpE                    details on connecting to OpenVMS from various UNIX                     platforms.   H                    For other keymapping information, see Section 11.7.1.      J                                                                      11-11                                   DECwindowsD      D           __________________________________________________________<           11.8  Why doesn't XtAppAddInput() work on OpenVMS?  F                    Yes, XtAppAddInput()  does work on OpenVMS. The MITC                    definition of the X Windows call XtAppAddInput() 8                    includes platform-specific arguments.  D                    On platforms where C is the typically the primaryB                    programming language for the platform, the fileA                    descriptor mask is one of the arguments to the_)                    XtAppAddInput()  call.   F                    On OpenVMS, the platform-specific arguments to thisG                    call include an event flag and an IOSB, as these are I                    the traditional OpenVMS constructs used to synchronizeiF                    the completion of asynchronous operations. While itH                    would be easier to port non-OpenVMS C code that callsD                    XtAppAddInput()  over to OpenVMS if the argumentsF                    included the C file descriptor, this would make theH                    call unusable from other OpenVMS languages, and wouldF                    make it extremely difficult to use OpenVMS features2                    such as ASTs and sys$qio calls.  D                    One restriction on the event flag: the event flagJ                    chosen must be from event flag cluster zero. When usingF                    the traditional lib$get_ef and lib$free_ef calls toF                    allocate and deallocate event flags, you must firstJ                    explicitly call lib$free_ef to free up some event flagsH                    in event flag cluster zero. Please see the event flagH                    documentation for specific details on these calls andF                    for specific event flags that can be freed in event%                    flag cluster zero.e  E                    Here is some example code that covers calling thisg&                    routine on OpenVMS:                                        11-12 o  u                              DECwindowsa        2                        m->InputID = XtAppAddInput(%                            m->AppCtx,e&                            m->InputEF,(                            m->InputIosb,-                            the_callback, 1 ); 1                        if ( !((int) m->InputID ))                             {)                            XtAppErrorMsg( )                                m->AppCtx,u/                                "invalidDevice", /                                "XtAppAddInput", 0                                "XtToolkitError",5                                "Can't Access Device",p/                                (String *) NULL, 3                                (Cardinal *) NULL );                             ...  D           __________________________________________________________J           11.9  Why do the keyboard arrow keys move the DECwindows cursor?  E                    Congratulations, you have just stumbled into "dead F                    rodent" mode. This DECwindows environment-where theF                    keyboard arrow keys move the mouse cursor and whereJ                    the [SELECT], [PREV], and [NEXT] keys emulate the threeJ                    mouse buttons-allows rudimentary system operations when5                    the mouse is among the casualties._  A                    To enter or exit "dead rodent" mode, enter theE-                    following: <CTRL/SHIFT/F3>l  D           __________________________________________________________;           11.10  Why does half my DECwindows display blank?   I                    This is likely a result of receiving an OPCOM or other[E                    console message on a system that shares the systemmC                    console with the DECwindows graphics workstation                     display.a  F                    You can toggle off the console display window usingD                    <CTRL/F2> and you can enable a serial console per6                    Section 14.3.6 or Section 14.3.3.3.      J                                                                      11-13 T                                 DECwindowso        B                    Also see the console message window applicationG                    available with recent DECwindows versions-DECwindows D                    versions V1.2-3 and later will enable this windowB                    by default. For details on this console messageC                    window, see the DECW$CONSOLE_SELECTION option in.@                    SYS$STARTUP:DECW$PRIVATE_APPS_SETUP.TEMPLATE.  F                    On older releases, you can disable output using the                    following:   =                    $ SET TERMINAL/PERMANENT/NOBROADCAST OPA0: 2                    $ DEFINE/USER SYS$COMMAND OPA0:"                    $ REPLY/DISABLE  I                    Also see Section 14.3.3.2, Section 14.17, and Also seel                    Section 8.4,s  D           __________________________________________________________C           11.11  %DECW-W-NODEVICE, No graphics device found on this                   system?  2                    To resolve the following error:  L                    %DECW-W-NODEVICE, No graphics device found on this systemQ                    -DECW-I-NODECW, DECwindows graphics drivers will not be loaded$  G                    o  Ensure that the system parameter WINDOW_SYSTEM is1G                       set to 1. If it is not set to a value of 1, issue_#                       the commands:_  -                       $ run sys$system:sysgen !                       USE CURRENT )                       SET WINDOW_SYSTEM 1T"                       WRITE ACTIVE#                       WRITE CURRENT                        EXIT  -                       Then reboot the system.i  H                    o  On OpenVMS Alpha, ensure the SYSMAN IO PREFIX LISTI                       is set correctly, and specifically ensure the DECW$ G                       prefix is included in the existing list. If it isn3                       not, you will need to add it:                       11-14 R                                 DECwindows         !           $ run sys$system:sysman            IO SHOW PREFIXI           IO SET PREFIX=(DECW$,*)   * = list returned by the show command            IO AUTO/LOG            EXIT  F                    o  Ensure that the image SYS$SHARE:DECW$ICBM.EXE isG                       installed in memory. If it is not installed, thenf!                       install it:.  1           $ INSTALL LIST/FULL SYS$SHARE:DECW$ICBMt/           $ INSTALL REPLACE SYS$SHARE:DECW$ICBM )           $ EDIT SYS$MANAGER:SYCONFIG.COM   4           $! The following line was added to install1           $! support for the Mach64 Graphics Cardi           $!/           $ INSTALL REPLACE SYS$SHARE:DECW$ICBM            $ ^Z  -                       Then reboot the system.:  I                       The ICBM mechanism is not used on and not needed byt6                       more recent DECwindows versions.  I                    o  If the system still complains "%DECW-W-NODEVICE, NoYB                       graphics device found on this system", then:  1                      o  Boot the system as normal   (                      o  Login as SYSTEM.  E                      o  Create the file SYS$COMMON:[SYSMGR]DECW$USER_ I                         AUTOCONFIG.DAT. Protection must permit world read                          access.o  H                      o  Add the following string on the very first line:  !           CLEAR_PFLAG = ISA_4BYTEt  %                      o  Save the fileC  0                      o  Set the file protections  D           $ SET PROTECTION=W:RE SYS$MANAGER:DECW$USER_AUTOCONFIG.DAT  )                      o  Reboot the systemE  )                    Also see Section 11.5.   J                                                                      11-15 n  s                              DECwindows       D           __________________________________________________________9           11.12  How can I reset the warning bell volume?   J                    With DECwindows CDE drivers and ECOs starting with ECOsG                    for the DECwindows keyboard driver SYS$IKBDRIVER.EXEGB                    in OpenVMS Alpha V7.1-2 and V7.2-1 and with theE                    SYS$IKBDRIVER.EXE included in OpenVMS V7.2-1H1 and H                    later, the DECwindows CDE controls will now correctlyA                    manage the setting of the warning bell volume._  F                    Unfortunately, the equivalent controls in the olderH                    DECwindows Motif interface are not compatible and can<                    no longer manage the warning bell volume.  J                    If you need to manage the volume with DECwindows Motif,9                    consider using the following approach:n  2                    $ @decw$utils:decw$define_utils%                    $ xset b 1 100 100t  D                    The numerics are the volume, pitch, and duration,                     respectively.  J                    Why? When OpenVMS first started supporting the PC-styleJ                    keyboards, the X Windows Server and the keyboard driverH                    interface did not support the pitch and duration, andH                    neither did DECwindows Motif. The DECwindows keyboardH                    driver was accordingly changed to use the volume fromE                    the keyclick setting (keyclick is not available inhF                    a PC-style keyboard) and the bell volume setting to2                    control the pitch and duration.  H                    DECwindows CDE does provide sliders for setting pitchE                    and duration, so the keyboard driver and X WindowstJ                    Server were modified to provide all of the information,J                    and now the DECwindows CDE sliders work. This change isI                    unfortunately incompatible with the old scheme used onaH                    the pre-CDE desktops, and the volume controls are nowH                    incompatible with the current keyboard drivers. Hence#                    the use of xset.e                              11-16                                   DECwindowsn      D           __________________________________________________________=           11.13  How can I alter the DECwindows CDE backdrop?d  H                    To select a separate backdrop to be displayed on each/                    screen using DECwindows CDE:p  J                    o  Click on the Application Manager. This is the drawer.                       icon on the CDE toolbar.  ,                    o  Click on Desktop Tools  I                    o  Click on Set Default Screen and select the required                        screen  A                    o  Click on the Style Manager. This is the oneaE                       containing the mouse and ttt on the CDE toolbarp  0                    o  Now change the background.  D           __________________________________________________________A           11.14  How can I enable the DECwindows TCP/IP Transportc  D                    To configure the TCP/IP transport for DECwindows,F                    first ensure that a TCP/IP package is installed andC                    configured. Then set the DCL symbol DECW$SERVER_tA                    TRANSPORTS in SYS$MANAGER:DECW$PRIVATE_SERVER_gE                    SETUP.COM to the appropriate local value, based onnJ                    the comments in that file. If you do not have a copy ofI                    SYS$STARTUP:DECW$PRIVATE_SERVER_SETUP.COM, the use thenJ                    following COPY command to create this file based on the*                    provided template file:  A           $ COPY SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.TEMPLATE -e=           $_ SYS$COMMON:[SYSMGR]DECW$PRIVATE_SERVER_SETUP.COMn  D           __________________________________________________________G           11.15  Can I use DECwindows 1.2-* on OpenVMS V7.3-2 or later?a  *                    The short answer is no.  F                    OpenVMS Alpha V7.3-2 only supports DECwindows MotifF                    V1.3 and later. If you require DECwindows V1.2-6 orI                    earlier, then you are limited to operations on OpenVMSC5                    Alpha V7.3-1 and earlier releases.M  F                    The central technical reason involves depdendenciesJ                    among the parts of the X11 subsystem that are deliveredI                    with the base OpenVMS operating system including the XeG                    Windows display server and the transport images, ando  J                                                                      11-17                                   DECwindowst        I                    the parts of the DECwindows product that are deliveredMH                    within the DECwindows installation kits including theD                    client libraries and the DECwindows applications.  H                    DECwindows V1.3 and later made substantial changes toH                    the transport layer, and these required correspondingI                    changes to both the associated client and server code. I                    OpenVMS Alpha V7.3-2 includes the server and transport E                    with the V1.3 modifications. These changes were in H                    support of the upgrade of Xlib from X11R5 to X11R6.6,I                    and transport-level changes associated with support of 1                    the Kerberos and LBX features.a  J                    If you attempt to load DECwindows V1.2-6 images onto anG                    OpenVMS Alpha V7.3-2 or later system, the DECwindowsrF                    libraries will not function with with system imagesH                    and will particularly not function with the transport                    layer.   D           __________________________________________________________2           11.16  How to add Fonts into DECwindows?  F                    The following assumes DECwindows V1.3-1 and OpenVMSJ                    Alpha V7.3-2 and later unless stated otherwise, and canG                    permit fonts of various formats to be added into the *                    DECwindows environment.  E                    The recommended location for user font files is to C                    place them in the directories which are reserved_@                    for this purpose, typically located below the7                    SYS$COMMON:[SYSFONT.DECW] directory.T  8                    SYS$COMMON:[SYSFONT.DECW.USER_100DPI]7                    SYS$COMMON:[SYSFONT.DECW.USER_75DPI],  J                    The above are recommended for PCF files of 100 Dots PerE                    Inch (DPI) and of 75 DPI resolution, respectively.T  8                    SYS$COMMON:[SYSFONT.DECW.USER_COMMON]  E                    The above is recommended for other PCF files, such H                    as terminal (character cell) fonts, and fonts used by)                    specific applications.   :                    SYS$COMMON:[SYSFONT.DECW.USER_CURSOR16]:                    SYS$COMMON:[SYSFONT.DECW.USER_CURSOR32]                      11-18 e