 





                   OpenVMS Programming Information




                   Additional information and examples for OpenVMS are
                   available via:

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9. and
                   via:

                   o  http://www.openvms.compaq.com/freeware/

          __________________________________________________________
          10.3  How do I get the arguments from the command line?

                   If you're writing a program and want to accept
                   arguments from a foreign command, you can use LIB$GET_
                   FOREIGN to get the command line and parse it yourself,
                   or if you're programming in C, use the normal argc/argv
                   method.

                   To write an application which uses the normal DCL
                   verb/qualifier/parameter syntax for invocation, see
                   the description of the CLI$ routines in the OpenVMS
                   Callable Utility Routines Reference Manual.

                   It is possible to write an application which can be
                   used both ways; if a DCL verb isn't used to invoke
                   the image, the application parses the command line
                   itself. One way to do this is to call CLI$GET_VALUE for
                   a required parameter. If it is not present (or you get
                   an error), call LIB$GET_FOREIGN to get the command line
                   and do the manual parse.

                   See also Section 8.1.

          __________________________________________________________
          10.4  How do I get a formatted error message in a variable?

                   Use the SYS$PUTMSG system service with an action
                   routine that stores the message line(s) in the variable
                   of your choice. Be sure the action routine returns
                   a "false" (low bit clear) function value so that
                   SYS$PUTMSG doesn't then try to display the message
                   (unless you want it to.) See the description of $PUTMSG
                   in the System Services Reference Manual for an example
                   of using an action routine.

                   10-4

 





                   OpenVMS Programming Information



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

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

                   Also see Section 10.11, particularly for pointers to
                   the details on shareable images and shareable image
                   creation.

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

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

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

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

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

                   By default, COMMON PSECTs in HP Fortran for OpenVMS
                   Alpha (as well as most other OpenVMS Alpha compilers)
                   are NOSHR. On VAX, the default was SHR which required
                   you to change the attribute to NOSHR if you wanted

                                                                      10-5

 





                   OpenVMS Programming Information




                   your COMMON to be in a shareable image but not write-
                   shared by all processes on the system. If you do want
                   write-sharing, use:

                   CDEC$ PSECT common-name=SHR

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

                   For further information, see the Linker manual.

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

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

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

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

                   For further floating-point related information, see:

                   o  http://www.hhs.dk/anonymous/pub/vms/collection/ieee.zip

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

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

                   10-6

 





                   OpenVMS Programming Information




                   IARGCOUNT, which is also available in DEC Fortran on
                   OpenVMS VAX.

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

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

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

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

                   For information on licensing, please see Section 12.5.

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

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9.





                                                                      10-7

 





                   OpenVMS Programming Information



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

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

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

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

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

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



                   10-8

 





                   OpenVMS Programming Information




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

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

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9.

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

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

          __________________________________________________________
          10.13  What is a descriptor?

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

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

                                                                      10-9

 





                   OpenVMS Programming Information




                       #include {descrip.h}
                       #include {lib$routines.h}
                       #include {stsdef.h}
                       int RetStat;
                       char TxtBuf[TXTSIZ]
                       struct dsc$descriptor StaticDsc =
                         { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL };
                       struct dsc$descriptor DynDsc =
                         { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };
                       int DynDscLen = 255;
                       $DESCRIPTOR( ConstDsc, "This is a string" );

                       /* finish setting up a static descriptor */
                       StaticDsc.dsc$w_length      = TXTSIZ;
                       StaticDsc.dsc$a_pointer     = (void *) TxtBuf;

                       /* finish setting up a dynamic descriptor */
                       RetStat = lib$sget1_dd( &DynDscLen, &DynDsc );
                       if ( !$VMS_STATUS_SUCCESS( RetStat ) )
                         return RetStat;

                       /* release the dynamic storage */
                       RetStat = lib$sfree1_dd( &DynDsc );
                       if (!$VMS_STATUS_SUCCESS( RetStat ))
                         return RetStat;

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

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

                   10-10

 





                   OpenVMS Programming Information




                   associated with the dynamic descriptor, as required.
                   Routines can obviously access and alter the contents of
                   the storage referenced by the descriptor.

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

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

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

                   o  http://www.hhs.dk/anonymous/pub/vms/misc/FORTRAN_C_
                      CALL.COM

                   o  ftp://ftp.hhs.dk/pub/vms/misc/FORTRAN_C_CALL.COM

          __________________________________________________________
          10.14  How do I create a process under another username?

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

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

                                                                     10-11

 





                   OpenVMS Programming Information




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

                   Typical mechanisms for creating a process under another
                   username include:

                   o  personna services around a sys$creprc call. See
                      above.

                   o  via DECnet task-to-task, using explicit
                      specification of username and password, or using
                      a DECnet proxy. This creates a network-mode job
                      under the target user. The network-mode job might
                      do little more than a RUN/DETACH of an image passed
                      in via task-to-task-task-to-task communications
                      are fully available using strictly DCL-to-DCL
                      processing, or using a compiled language and DCL,
                      etc.)

                   o  SUBMIT/USER, or the username argument on the
                      sys$sndjbc call. This creates a batch-mode job under
                      the specified username. The batch-mode job might do
                      little more than a RUN/DETACH of an image passed in
                      via a parameter.

                   o  the UIC argument on the sys$creprc call. This mimics
                      the UIC of the target user, and is certainly not the
                      prefered mechanism for this task.

                   o  Via pseudo-terminals...

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




                   10-12

 





                   OpenVMS Programming Information



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

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

                   Detached processes typically do not have a CLI present.

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

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

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

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

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

                   Bliss language source code that contains the following
                   statement:

                     LIBRARY 'SYS$LIBRARY:STARLET.L32';

                                                                     10-13

 





                   OpenVMS Programming Information




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

                   STARLET.L32 contains the public interfaces to OpenVMS:

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

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

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

                   The equivilent files for Bliss64 are created with:

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

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

                   !
                   ! This is the OpenVMS VAX version of ARCH_DEFS.REQ, and
                   ! contains the architectural definitions for conditionally
                   ! compiling OpenVMS Bliss sources for use on VAX systems.
                   ! (If you should encounter compilation errors here, please
                   ! seriously consider upgrading your Bliss compiler.)
                   !
                   MACRO VAXPAGE = 1%;
                   MACRO BIGPAGE = 0%;
                   !
                   MACRO VAX =                     ! = 1 if compiled BLISS/VAX
                           %BLISS(BLISS32V)%;      ! = 0 if not compiled BLISS/VAX

                   MACRO EVAX =                    ! = 1 if compiled BLISS/E* (Obsolete, old name)
                           (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn

                   MACRO ALPHA =                   ! = 1 if compiled BLISS/E* (New arch name)
                           (%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn

                   MACRO IA64 =                    ! = 1 if compiled BLISS/I* (New arch name)
                           (%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /Ann

                   10-14

 





                   OpenVMS Programming Information




                   MACRO ADDRESSBITS =
                           %BPADDR%;               ! = 32 or 64 based on compiler used

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

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

          __________________________________________________________
          10.17  How can I open a file for shared access?

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

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

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9.

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

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

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

                                                                     10-15

 





                   OpenVMS Programming Information



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

                   #include {lib$routines.h}
                   #include {ssdef.h}
                   #include {string.h}

                   main()
                       {
                       char ascic_debug_commands[128];
                       char *dbgcmd = "*show calls;go;exit";

                       strcpy( ascic_debug_commands, dbgcmd );
                       ascic_debug_commands[0] = (char) strlen( dbgcmd ) -
          1;

                       lib$signal(SS$_DEBUG,1,ascic_debug_commands);

                       return 1;
                       }

          __________________________________________________________
          10.20  Dealing with Endian-ness?

                   OpenVMS on VAX, OpenVMS on Alpha and OpenVMS on Intel
                   IA-64 platforms (as well as all Microsoft Windows
                   implementations and platforms) all support and all
                   use the little-endian byte ordering. Certain Alpha
                   microprocessors and certain Intel Itanium processors
                   can be configured to operate in big-endian and
                   potentially in bi-endian mode. HP-UX typically operates
                   big-endian.

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

                   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 C
                   library and the TCP/IP Services XDR (eXternal Data
                   Representation) libraries. One of the more recently
                   introduced network formats, and one that is seeing
                   extensive press and marketing coverage, is XML.

                   10-16

 





                   OpenVMS Programming Information



          __________________________________________________________
          10.21  How to resolve LINK-I-DATMISCH errors?

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

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

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

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

          __________________________________________________________
          10.22  HP C and other OpenVMS C Programming Considerations?

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

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

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

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

                                                                     10-17

 





                   OpenVMS Programming Information




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

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

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

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

                   o  /PREFIX=ALL_ENTRIES


                   10-18

 





                   OpenVMS Programming Information




                      As mentioned above. Failure to specificy this
                      qualifier can cause the compiler to not add the
                      prefixes for the names of the C library routines
                      into the references placed in the object module,
                      which can in turn cause problems resolving the
                      external symbols in the library when the object
                      code is linked.

                   o  /ASSUME=WRITABLE_STRING_LITERALS

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

                   o  /SHARE_GLOBALS

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

                   o  /EXTERN_MODE=COMMON_BLOCK

                      VAX C assumes common block model for external
                      linkages.

                   o  /[NO]MEMBER_ALIGNMENT

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

                   o  /WARN=ENABLE=(LEVEL4,QUESTCODE)/STANDARD=PORT/ACCEPT=NOVAXC_
                      KEYWORDS

                      Enables all manner of useful compiler diagnostics.

                      You can disable extraneous diagnostics with the
                      following:



                                                                     10-19

 





                   OpenVMS Programming Information




                      #ifdef __DECC
                      #pragma message save
                      #pragma message disable /* insert message tag here */
                      #endif

                   Permit structure members to be naturally aligned
                   whenever possible, and avoid using /NOMEMBER_
                   ALIGNMENT. If you need to disable member alignment,
                   use the equivilent #pragma to designate the specific
                   structures. The alignment of structure members normally
                   only comes into play with specific unaligned data
                   structures-such as the sys$creprc quota itemlist-
                   and with data structures that are using data that was
                   organized by a system using byte or other non-member
                   alignment.

                   Versions of HP C such as V6.0 include the capability to
                   extract the contents of the standard header libraries
                   into directories such as SYS$SYSROOT:[DECC$LIB...],
                   and provide various logical names that can be defined
                   to control library searches. With HP C versions such
                   as V6.0, the default operations of the compiler match
                   the expectations of most OpenVMS programmers, without
                   requiring any definitions of site-specific library-
                   related logical names. (And logical names left from
                   older DEC C versions can sometimes cause the compiler
                   troubles locating header files.)

                   HP C V5.6 and later include a backport library, a
                   mechanism by which HP C running on older OpenVMS
                   releases can gain access to newer RTL routines added
                   to the RTL in later OpenVMS releases-the language RTLs
                   ship with OpenVMS itself, and not with the compilers.

                   Example C code is available in SYS$EXAMPLES:, in
                   DECW$EXAMPLES (when the DECwindows examples are
                   installed), in TCPIP$SERVICES (or on older releases,
                   UCX$EXAMPLES) when HP TCP/IP Services is installed), on
                   the Freeware CD-ROMs, and at web sites such as

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9.

                   10-20

 





                   OpenVMS Programming Information



          _____________________________
          10.22.1  Other common C issues

                   The localtime()  function and various other functions
                   maintain the number of years since 1900 in the "struct
                   tm" structure member tm_year. This field will contain a
                   value of 100 in the year 2000, 101 for 2001, etc., and
                   the yearly incrementation of this field is expected to
                   continue.

                   The C epoch typically uses a longword (known as time_
                   t) to contain the number of seconds since midnight
                   on 1-Jan-1970. At the current rate of consumption of
                   seconds, this longword is expected to overflow (when
                   interpreted as a signed longword) circa 03:14:07 on
                   19-Jan-2038 (GMT), as this time is circa 0x7FFFFFFF
                   seconds since the C base date. (The most common
                   solution is to ensure that time_t is an unsigned.)

                   If C does not correctly handle the display of the
                   local system time, then check the UTC configuration
                   on OpenVMS-the most common symptom of this is a skew of
                   one hour (or whatever the local daylight savings time
                   change might be). This skew can be caused by incorrect
                   handling of the "is_dst" setting in the application
                   program, or by an incorrect OpenVMS UTC configuration
                   on the local system. (See section Section 4.3.)

                   Floating point is prohibited in OpenVMS Alpha inner-
                   mode (privileged) code, and in any process or other
                   execution context that does not have floating point
                   enabled. C programmers developing and working with
                   OpenVMS Alpha high-IPL kernel-mode code such as device
                   drivers will want to become familiar with the floating
                   point processing available in the environment, and with
                   the C compiler qualifier /INSTRUCTION_SET=[NO]FLOATING_
                   POINT. Device drivers and other similar kernel-mode C
                   code must be compiled with /INSTRUCTION_SET=FLOATING_
                   POINT and /EXTERN_MODEL=STRICT_REFDEF.

                   Additionally, the SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY
                   parameter will be needed to be appended to the module
                   specification or declared via the C compiler's include
                   library logical name mechanism when the C compiler is
                   resolving kernel-mode data structures and definitions.
                   This library contains OpenVMS kernel-mode and other

                                                                     10-21

 





                   OpenVMS Programming Information




                   system declaractions, and particularly a mixture
                   of undocumented definitions and declarations, and
                   particularly definitions and declarations that are
                   subject to change (and that can accordingly lead to
                   requirements for the recompilation of application
                   code).

                   In addition to the user-mode C Run-Time Library (RTL)
                   mentioned in the OpenVMS C RTL documentation and
                   referenced over in Section 3.11, there is a second and
                   parallel kernel-mode RTL accessable to device drivers
                   and other kernel code on OpenVMS Alpha and OpenVMS
                   I64. The most common time this second C library is
                   noticed is when C code is (erroneously) linked with
                   /SYSEXE/SYSLIB, and duplicate symbol errors typically
                   then arise. As code running in supervisor-, executive-
                   or kernel-mode context cannot call out a user-mode
                   RTL or other user-mode library, you will want to
                   respecify the command as LINK /SYSEXE/NOSYSLIB. This
                   will eliminate the duplicate symbol errors, since only
                   the kernel-mode library will be referenced, and it will
                   also avoid calling out into the user-mode libraries.

                   When sharing variables with other languages, here is
                   some example HP C code...

                         ...
                         #pragma extern_model save
                         #pragma extern_model strict_refdef
                         extern int   VMS$GL_FLAVOR;
                         #pragma extern_model restore
                         ...

                   and here is some associated example Bliss code...

                         ...
                         EXTERNAL
                            VMS$GL_FLAVOR,
                         ....





                   10-22

 





                   OpenVMS Programming Information



          _____________________________
          10.22.2  Other common C++ issues

                   HP C++ (a separate compiler from HP C) provides
                   both symbol mangling and symbol decoration. Some
                   of the details of working with longer symbol names
                   and the resulting symbol name mangling in mixed
                   language environments are listed in the shareable
                   image cookbook, and in the C++ documentation. Symbol
                   name decoration permits the overloading of functions
                   (by adding characters to the external symbol for
                   the function to indicate the function return type
                   and the argument data types involved), and mixed-
                   language external references can and often do need to
                   disable this decoration via the extern "C" declaration
                   mechanism:

                         extern "C"
                           {
                           extern int ExternSymbol(void *);
                           extern int OtherExternSymbol(void *);
                           }

                   Also see Section 14.7 for information on /ARCHITECTURE
                   and /OPTIMIZE=TUNE.

                   See Section 10.15 for information on the C system and
                   the lib$spawn call in CAPTIVE environments.

                   Constructs such as the order of incrementation or
                   decrementation and the order of argument processing
                   within an argument list are all implementation-defined.
                   This means that C coding constructs such as:

                       i = i++;
                       a[i] = i++;
                       foo( i, i++, --i);

                   are undefined and can have (adverse) implications when
                   porting the C code to another C compiler or to another
                   platform. In general, any combination of ++, -, =, +=,
                   -=, *=, etc operators that will cause the same value to
                   be modified multiple times (between what the ANSI/ISO C
                   standard calls "sequence points") produce undefined and
                   implementation-specific results.

                                                                     10-23

 





                   OpenVMS Programming Information




                   Within C, the following are the "sequence points":
                   the ";" at the end of a C statment, the ||, &&, ?:,
                   and comma operators, and a call to a function. Note
                   specifically that = is NOT a sequence point, and that
                   the individual arguments contained within a function
                   argument list can be processed from right to left, from
                   left to right, or at any random whim.

                   HP C for OpenVMS VAX (formerly DEC C) and VAX C do
                   differ in the related processing.

                   So you are looking for OpenVMS-specific definitions
                   (include files)?

                   UCBDEF.H, PCBDEF.H and other OpenVMS-specific
                   definitions-these are considered part of OpenVMS and
                   not part of the C compiler kit-are available on all
                   recent OpenVMS Alpha releases.

                   To reference the version-dependent symbol library
                   sys$share:sys$lib_c.tlb, use a command similar to the
                   following for compilation:

                   $ CC sourcea+SYS$LIBRARY:SYS$LIB_C/LIB

                   You can also define DECC$TEXT_LIBRARY to reference the
                   library.

                   You will want to review the Programming Concepts
                   manual, and specifically take a quick look at Chapter
                   21.

                   And some general background: the STARLET definitions
                   (and thus the sys$starlet_c.tlb library) contain the
                   symbols and the definitions that are independent of
                   the OpenVMS version. The LIB definitions (and thus
                   sys$lib_c) contain symbols and definitions that can
                   be dependent on the OpenVMS version. You won't need to
                   rebuild your code after an OpenVMS upgrade if you have
                   included definitions from STARLET. The same cannot be
                   said for some of the definitions in LIB-you might need
                   to rebuild your code. (The UCB structure can and has
                   changed from release to release, for instance.)

                   Recent versions of C automatically search sys$starlet_
                   c.tlb. Explicit specification of sys$lib_c.tlb is
                   required.

                   10-24

 





                   OpenVMS Programming Information




                   Also see the Ask The Wizard website topics (2486),
                   (3803), and (1661):

                   o  http://www.hp.com/go/openvms/wizard/

                   For additional information on the OpenVMS Ask The
                   Wizard (ATW) area and for a pointer to the available
                   ATW Wizard.zip archive, please see Section 3.9.

                   See Section 9.5 for information on the C off_t
                   limitations, resolved in OpenVMS V7.3-1 and later and
                   in ECO kits available for specific OpenVMS releases.
                   The use of a longword for off_t restricts applications
                   using native C I/O to file sizes of two gigabytes or
                   less, or these applications must use native RMS or XQP
                   calls for specific operations.

          __________________________________________________________
          10.23  Status of Programming Tools on OpenVMS VAX?

                   DECthreads V7.3 and the HP C compiler (also known as
                   Compaq C and DEC C) V6.4 are presently expected to
                   be the last updates and the last releases of these
                   development packages for use on OpenVMS VAX. The run-
                   time support for both DECthreads (CMA$RTL) and for C
                   (DECC$CRTL) will continue to be maintained, and will
                   continue to be available on OpenVMS VAX. The VAX C
                   V3.2 compiler is the final VAX C compiler release for
                   OpenVMS VAX, and the VAX C Run-Time Library (VAXCRTL)
                   will also continue to be available.

                   New development and new features and product
                   enhancements continue for the OpenVMS Alpha and the
                   OpenVMS IA-64 DECthreads and C compilers.

          __________________________________________________________
          10.24  Choosing a Version Number for Application Code?

                   One of the common rules-of-thumb for choosing a version
                   number for a new version of a layered product or
                   an application, and its expected effects on client
                   applications and users, follows:

                   o  No functional and no application-visible changes,
                      bugfixes only-the edit number is incremented.
                      These tend to be very small, very isolated, or ECO-
                      level changes. These can also be distributions for

                                                                     10-25

 





                   OpenVMS Programming Information




                      specific hardware configurations or platforms, as
                      is the case with an OpenVMS Limited Hardware Release
                      (LHR). Application rebuilds are not expected, and
                      there is an assumption that general user-provided
                      application-related regression testing will not be
                      required.

                   o  Minimal functional and very few user-visible
                      changes-the maintenance number is incremented. These
                      tend to be very small or even ECO-level changes,
                      though somewhat larger than an edit-level change.
                      Application rebuilds are not expected, and there is
                      an assumption that user-provided application-related
                      regression testing will not be required.

                   o  Various small and upward-compatible functional
                      changes-the minor version number is incremented.
                      The changes are user-visible, and are intended to be
                      user-visible. Application rebuilds are not expected.
                      Some application programmers may choose to perform
                      regression tests.

                   o  Large and/or potentially incompatible changes-
                      the major version number is incremented. Some
                      applications might need to be rebuilt. Various
                      application programmers will choose to perform
                      regression tests of their respective applications.

                   For additional version-numbering materials and for
                   information on assigning module generation numbers,
                   please see the OpenVMS (POLYCENTER) Software Product
                   Installation Utility-variously refered to by acronyms
                   including PCSI and SPIA-reference manual available
                   within the OpenVMS documentation set.

                   Of course, all of this is obviously subject to
                   interpretation, particularly around the distinction
                   between large and small changes and such. The scale
                   of the application is also a factor, as larger and
                   more complex applications will tend toward smaller
                   increments and will tend to see the maintenance number
                   incremented, while new releases of smaller applications
                   will tend to see the minor version incremented somewhat
                   more frequently.

                   10-26

 





                   OpenVMS Programming Information




                   The goal of all this is to provide a guide to relative
                   scale of changes and the associated effort involved
                   in an upgrade for the user and/or for the application
                   programmer.

          __________________________________________________________
          10.25  Selecting a Process Dump Directory?

                   You can customize the device and directory for the
                   process dump by defining the logical names SYS$PROCDMP
                   and SYS$PROTECTED_PROCDMP. The former is for non-
                   privileged dumps, while the latter is the location
                   where privileged image dumps are written, and
                   preferably an area protected against untrusted access.
                   For example:

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

                   The abouve presumes that the SYS$ERRORLOG logical name
                   points to a valid location.

                   There is presently no means to change the name of the
                   generated dump file from IMAGENAME.DMP to something
                   else. Accordingly, you will want to use different
                   target directories for this purpose, particularly
                   if there is more than one application or process
                   potentially writing process dumps.

          __________________________________________________________
          10.26  Access to Itanium Assembler?

                   If you are interested in accessing the native
                   Intel Itanium assembler within the OpenVMS I64 GNV
                   environment-and since the iasi64 assembler is a Unix
                   program and GNV is a Unix environment for OpenVMS I64-
                   you can simply copy iasi64.ext into your gnu:[bin]
                   directory in place of "as.", and of "AS.EXE".

                   Alternately and probably also better, you can write an
                   "as." script to invoke the iasi64.exe image from its
                   particular prefered location on the local system.

                   A typical "as." script looks like this:

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

                                                                     10-27

 










                   _______________________________________________________

          11       DECwindows



          __________________________________________________________
          11.1  How do I let someone else display something on my
                workstation?

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

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

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

          ________________________________________________________________
          Table 11-1  X Windows Display Commands

                   _______________________________________________________
                   Shell_____Command______________________________________

                   csh

                             # setenv DISPLAY vms.domain:0.0

                   sh and ksh

                             # $ DISPLAY=vms.domain:0.0 ; export DISPLAY

                   DCL

                             $ SET DISPLAY/CREATE/NODE=vms.domain -
          ___________________/TRANSPORT=TCPIP/SERVER=server/SCREEN=screen_

                   o  If you have verified the command is correct and
                      things are still not working, ensure the Security
                      settings on the OpenVMS host side will allow the

                                                                      11-1

 





                   DECwindows




                      incoming connection: Pull down the "Options" menu
                      in the Session Manager, and select "Security...". If
                      you do not find your host and username and transport
                      listed among the authorized users, you will need to
                      add an entry.

                     o  There are various transports available, including
                        LOCAL, DECNET, LAT, and TCPIP. You must Select
                        the transport appropriate to the incoming
                        connection.

                     o  If the transport is "DECnet", do NOT add the
                        double colon (::) to the node name.

                     o  If the transport is "TCPIP", "Username" must
                        be an asterisk (*). Why? Because unlike DECnet,
                        the TCP/IP protocol does not provide the remote
                        username information in the incoming connection.

                     o  If the connection is "TCPIP", it is best to use
                        a full domain name (e.g. Node.Subd.Domain).
                        However, you may have to use the IP address
                        itself, if your host does not have a way to
                        resolve the address via DNS. If you have the
                        luxury of fixed addresses (eg: you are not using
                        DHCP), then it can be helpful to add two entries
                        for each TCP/IP host, one that specifies the host
                        name and one that specifies the host address.

                     o  There are various TCP/IP packages for OpenVMS,
                        and you must use syntax appropriate to the
                        transport installed.

                     o  If a TCP/IP connection is still not working,
                        ensure that the transport you want has been
                        activated for use with DECwindows. See
                        Section 11.14 for details of configuring TCP/IP
                        as a transport.

                   o  There is a log file created in SYS$MANAGER: which
                      can tell you which transports are loaded, and
                      also tell you what connect attempts were rejected,
                      including showing what the presented credentials
                      were. This file is SYS$MANAGER:DECW$SERVER_0_
                      ERROR.LOG, although the 0 could be another number
                      if you have multiple servers on the workstation. I

                   11-2

 





                   DECwindows




                      have found this file to be very useful for tracking
                      down what needs to be put in the Session Manager
                      Security entries.

          __________________________________________________________
          11.2  How do I create a display on another workstation?

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

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

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

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

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

                   Use the undocumented SHOW DISPLAY/SYMBOL, and then
                   reference the symbols DECW$DISPLAY_NODE, DECW$DISPLAY_
                   SCREEN, DECW$DISPLAY_SERVER and/or DECW$DISPLAY_
                   TRANSPORT.

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

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

          Look in the Freeware V4.0 directory /srh_examples/DECUS_UNDOC_
          CLINIC/.


                                                                      11-3

 





                   DECwindows



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

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

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

          __________________________________________________________
          11.5  Why is DECwindows Motif not starting?

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

                   o  OpenVMS has failed to find the appropriate IRQ
                      information for an EISA graphics card (on the
                      DEC 2000 series) such as the HP (Compaq) QVision,
                      and did not autoconfigure it. Run the correct ECU
                      (for Tru64 UNIX and OpenVMS) and reboot. This is
                      necessary only on EISA-based systems.

                   o  You have an EISA-based system (such as the DEC
                      2000 model 300) and do not have a HP (Compaq)
                      QVision video card. This EISA graphics card should
                      have Compaq printed on it, and identifies itself
                      as a CPQ3011 or a CPQ3111. If it is not one of
                      these two EISA devices, then OpenVMS does not
                      support it. (There are no other supported EISA
                      graphics controllers, and EISA graphics are normally
                      used with DECwindows only on the DEC 2000 series
                      systems.)

                   o  You have a PCI-based system, and do not have a
                      supported graphics controller-examples of supported
                      controllers include the following:

                     o  PowerStorm 3D30

                     o  PowerStorm 4D20

                     o  PowerStorm 300

                   11-4

 





                   DECwindows




                     o  PowerStorm 350

                     o  ELSA GLoria Synergy

                     o  3DLabs Oxygen VX1

                      See Section 5.16 for further information on some of
                      these graphics controllers.

                   o  You have booted the system minimally, or have
                      otherwise disabled the device autoconfiguration
                      process.

                   If there is a G* graphics device present:

                   o  There may have been a severe error in the
                      DECwindows startup. Type the contents of
                      SYS$MANAGER:DECW$SERVER_0_ERROR.LOG for any
                      information on errors starting the server.

                   o  The system parameter WINDOW_SYSTEM is not set to
                      1. While this was a common way for system managers
                      to disable the DECwindows server startup, it is
                      not particularly reliable as DECwindows can now
                      "correct" this setting.

                      If you really do not want an OpenVMS system with
                      workstation hardware to bootstrap and configure
                      itself as a workstation, add the following
                      definition to SYLOGICALS.COM:

                      $ DEFINE/SYSTEM/EXEC DECW$IGNORE_WORKSTATION TRUE

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

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

                      and examine the information displayed. Make sure
                      that one of these licenses is present, valid and
                      active.

                      For information on registering software license
                      product authorization keys (PAKs) when you
                      cannot log into the system directly, please see
                      Section 5.6.2.

                                                                      11-5

 





                   DECwindows




                   o  Check that the DECW$PRIVATE_SERVER_SETUP.COM is
                      correct for the graphics controller in use. For
                      instance:

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

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

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

          __________________________________________________________
          11.6  How do I set the title on a DECterm window?

                   If you are creating a new DECterm window, check

                   $ HELP CREATE /TERMINAL /WINDOW_ATTRIBUTES

                   If you want to change the title of an existing window,
                   use the following control sequences, where <esc> is the
                   ANSI escape code, value decimal 27, and "text label" is
                   what you want to display:

                   To set the DECterm title, send the escape character,
                   then the characters "]21;", then the text label string,
                   and then an escape character followed by a backslash
                   character.

                   To set the icon label, send the escape character, then
                   the characters "]2L;", then the icon label string,
                   and then an escape character followed by a backslash
                   character.

                   11-6

 





                   DECwindows




                   To set both the DECterm title and icon to the full
                   device name, you can use the following DCL commands:

                   $  esc[0,7] = 27
                   $  fulldevnam = F$Edit(F$GetDVI("TT","FULLDEVNAM"),"UPCASE,COLLAPSE")
                   $  write sys$output esc+ "]21;" + fulldevnam + esc + "\"
                   $  write sys$output esc+ "]2L;" + fulldevnam + esc + "\"

                   You can also change the title and the icon using the
                   Options-Window... menu.

                   Also see Section 12.1 and Section 8.11.

          __________________________________________________________
          11.7  How do I customize DECwindows, including the login screen?

                   To customize various DECwindows Motif characteristics
                   including the defaults used by the SET DISPLAY command,
                   the DECwindows login screen background logo used (the
                   default is the DIGITAL, Compaq, or HP logo), various
                   keymaps (also see Section 11.7.2 and Section 11.7.1),
                   the FileView defaults, session manager defaults,
                   the DECwindows login processing, DECwindows log file
                   processing, and various other DECwindows attributes,
                   see the example file:

                   $ SYS$MANAGER:DECW$PRIVATE_APPS_SETUP.TEMPLATE

                   This example template file is typically copied over to
                   the filename SYS$COMMON:[SYSMGR]DECW$PRIVATE_APPS_
                   SETUP.COM and then modified to meet site-specific
                   requirements.

                   Additionally, various X tools such as xsetroot, bitmap
                   and xrdb-some these can be useful in customizing the
                   appearance of an application or of the DECwindows Motif
                   display-are provided in the DECW$UTILS: area.

                   When using DECwindows V1.2-4 and later on OpenVMS
                   Alpha, the default desktop is the Common Desktop
                   Environment (CDE). You can select your preferred
                   desktop (CDE or DECwindows Motif) when logging in,
                   or you can change the default to the DECwindows
                   Motif desktop using the DCL symbol decw$start_new_
                   desktop in the DECwindows private application setup
                   command procedure. See SYS$MANAGER:DECW$PRIVATE_APPS_

                                                                      11-7

 





                   DECwindows




                   SETUP.TEMPLATE for further details, and how to create
                   DECW$PRIVATE_APPS_SETUP.COM.

                   Note that with DECwindows CDE, the root window is
                   no longer visible by default. The root window is
                   hidden behind the "backdrop" window of the current
                   CDE workspace. To make the root window visible, use the
                   CDE style manager selection "backdrop none", and use
                   information such as that in the OpenVMS FAQ to set the
                   root window.

                   To add a new backdrop to the DECwindows CDE
                   environment, the backdrop must first be in or be
                   converted into X11 pixmap format. (This conversion
                   is often possible using tools such as xv.) Then (if
                   necessary) create the default backdrop directory
                   SYS$COMMON:[CDE$DEFAULTS.USER.BACKDROPS]. Place the
                   X11 pixmap file containing the desired image into the
                   backdrops directory, ensure that it has a filename
                   extension of .PM. (The xv default filename extension
                   for the X11 pixmap file is .XPM, while CDE expects
                   only to see files with .PM.) Now invoke the CDE style
                   manager and select a new backdrop. You will find
                   your image will be placed at the end of the list of
                   backdrops available.

                   If you require a message be included on the initial
                   display-where the start session display and the logo
                   appears-you can use either of the following approaches:

                      If you require a message on the initial display
                      where the start session and logo appears, you can
                      use the following approaches.

                      The simplest approach requires OpenVMS V7.3-2 or
                      later, and the corresponding DECwindows V1.3-
                      1 kit or later. You will want to create a file
                      named SYS$COMMON:[SYSMGR]DECW$GREET.TXT, and this
                      will be displayed in a popup-with an OK button-
                      when the login box is displayed. This is intended
                      specifically for applications requiring such a
                      display.


                   11-8

 





                   DECwindows




                      The second approach involves copying the file file:
                      SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.SYSTEM.CONFIG.C]XRESOURCES.DAT
                      to SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.USER.CONFIG.C]XRESOURCES.DAT,
                      and editing the copy. Specifically, look for the
                      following:

                      Dtlogin*greeting.labelString:

                      The line is normally commented out, and by default
                      contains the string:

                      Welcome to %localhost%

                      You can change this text to something akin to the
                      following:

                      Dtlogin*greeting.labelString:  Welcome to Heck \n\
                      This is a Trusted System owned by the Rulers of the planet Zark\n\
                      \n\
                      We Come In Peace\n\
                      \n
                      If you want Privacy, you've come to the wrong place\n\
                      \n

                      The lines of text will be centered for you.

                      In most DECwindows versions, you will be able to
                      onbtain only about eight (8) lines of text. Changes
                      have been implemented in DECwindows V1.3 and later
                      that permit up to about twenty-five (25) lines of
                      text.

                   o  The simplest approach requires OpenVMS V7.3-2 or
                      later, and the corresponding DECwindows V1.3-
                      1 kit or later. You will want to create a file
                      named SYS$COMMON:[SYSMGR]DECW$GREET.TXT, and this
                      will be displayed in a popup-with an OK button-
                      when the login box is displayed. This is intended
                      specifically for applications requiring such a
                      display.

                   o  The second approach involves copying the file
                      SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.SYSTEM.CONFIG.C]XRESOURCES.DAT
                      to SYS$SYSDEVICE:[VMS$COMMON.CDE$DEFAULTS.USER.CONFIG.C]XRESOURCES.DAT,
                      and editing the copy. Specifically, look for the
                      following text:

                                                                      11-9

 





                   DECwindows




                      Dtlogin*greeting.labelString:

                      The line is normally commented out, and by default
                      contains the string:

                      Welcome to %localhost%

                      You can change this text using the following syntax:

                      Dtlogin*greeting.labelString:  Unauthorized Access Permitted\n\
                      Press OK to Crash the System\n\
                      \n\
                      The Rulers of Zark are Such Kidders\n\
                      \n

                      Each line of text will be automatically centered.

                      In most DECwindows versions, you will be able to
                      obtain only about eight (8) lines of text here,
                      regardless of the font or other settings. Changes
                      have been implemented within DECwindows V1.3 and
                      later that permit up to about twenty-five (25) lines
                      of text using this mechanism.

                   The login logo is stored as an XPM bitmap image in the
                   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,
                   as DECwindows upgrades can replace the system version
                   of this file.

                   On DECwindows V1.3-1 and later (and possibly on V1.3),
                   both DECwindows CDE and DECwindows Motif displays use
                   this logo file. On older releases, only the DECwindows
                   CDE displays used this logo file, while the logo
                   used for the Motif login display was hard-coded into
                   the package and the only available override is the
                   DECW$LOGINLOGO command procedure mechanism within the
                   customized, site-specific DECW$PRIVATE_APPS_SETUP.COM
                   file.

                   Look at the contents of the DECDTLOGO.PM file and at
                   other *.XPM files and tools for additional details.


                   11-10

 





                   DECwindows



          _____________________________
          11.7.1  How do I customize DECwindows keymapping?

                   Various keymaps can be implemented on OpenVMS and other
                   X Windows systems, allowing the implementation of
                   a Dvorak-style or other alternate keymappings. For
                   details, see the available X Windows documentation
                   (this is the documentation associated with X Windows
                   itself, and not the product documentation for the
                   OpenVMS operating system nor for the DECwindows
                   X Windows implementation) and see the DECwindows
                   *.DECW$KEYMAP (text-format) files found in the
                   DECwindows DECW$KEYMAP: directory.

                   For other keymapping information, see Section 11.7.2.

          _____________________________
          11.7.2  Why does the DELETE key delete forward instead of
                  backward?

                   See the SET TERMINAL/BACKSPACE command on OpenVMS V8.1
                   and later.

                   This behaviour involves the Motif virtual key bindings.
                   When a Motif application starts, it looks at the vendor
                   string returned in the display connection information
                   and attempts to match the string to a table of virtual
                   bindings.

                   You can override the default bindings in your
                   decw$xdefaults.dat file. Here is the entry you would
                   make to get the default VMS bindings.













                                                                     11-11

 





                   DECwindows




                   *defaultVirtualBindings:\
                    osfCancel :  <F11> \n\
                    osfLeft :  <Left> \n\
                    osfUp  :  <Up> \n\
                    osfRight :  <Right> \n\
                    osfDown :  <Down> \n\
                    osfEndLine :Alt  <Right> \n\
                    osfBeginLine :Alt  <Left> \n\
                    osfPageUp :  <Prior> \n\
                    osfPageDown :  <Next> \n\
                    osfDelete :Shift  <Delete> \n\
                    osfUndo :Alt  <Delete> \n\
                    osfBackSpace :  <Delete> \n\
                    osfAddMode :Shift  <F8> \n\
                    osfHelp :  <Help> \n\
                    osfMenu :  <F4> \n\
                    osfMenuBar :  <F10> \n\
                    osfSelect :  <Select> \n\
                    osfActivate :  <KP_Enter> \n\
                    osfCopy :Shift  <DRemove> \n\
                    osfCut  :  <DRemove> \n\
                    osfPaste :  <Insert>

                   To merge:

                   $ xrdb :== $decw$utils:xrdb.exe
                   $ xrdb -nocpp -merge decw$xdefaults.dat

                   Also note that the DECW$UTILS:DECW$DEFINE_UTILS.COM
                   procedure can be used to establish the xrdb and other
                   symbols.

                   Also see the DECxterm directory of Freeware V5.0 for
                   details on connecting to OpenVMS from various UNIX
                   platforms.

                   For other keymapping information, see Section 11.7.1.







                   11-12

 





                   DECwindows



          __________________________________________________________
          11.8  Why doesn't XtAppAddInput() work on OpenVMS?

                   Yes, XtAppAddInput()  does work on OpenVMS. The MIT
                   definition of the X Windows call XtAppAddInput()
                   includes platform-specific arguments.

                   On platforms where C is the typically the primary
                   programming language for the platform, the file
                   descriptor mask is one of the arguments to the
                   XtAppAddInput()  call.

                   On OpenVMS, the platform-specific arguments to this
                   call include an event flag and an IOSB, as these are
                   the traditional OpenVMS constructs used to synchronize
                   the completion of asynchronous operations. While it
                   would be easier to port non-OpenVMS C code that calls
                   XtAppAddInput()  over to OpenVMS if the arguments
                   included the C file descriptor, this would make the
                   call unusable from other OpenVMS languages, and would
                   make it extremely difficult to use OpenVMS features
                   such as ASTs and sys$qio calls.

                   One restriction on the event flag: the event flag
                   chosen must be from event flag cluster zero. When using
                   the traditional lib$get_ef and lib$free_ef calls to
                   allocate and deallocate event flags, you must first
                   explicitly call lib$free_ef to free up some event flags
                   in event flag cluster zero. Please see the event flag
                   documentation for specific details on these calls and
                   for specific event flags that can be freed in event
                   flag cluster zero.

                   Here is some example code that covers calling this
                   routine on OpenVMS:










                                                                     11-13

 





                   DECwindows




                       m->InputID = XtAppAddInput(
                           m->AppCtx,
                           m->InputEF,
                           m->InputIosb,
                           the_callback, 1 );
                       if ( !((int) m->InputID ))
                           {
                           XtAppErrorMsg(
                               m->AppCtx,
                               "invalidDevice",
                               "XtAppAddInput",
                               "XtToolkitError",
                               "Can't Access Device",
                               (String *) NULL,
                               (Cardinal *) NULL );
                           ...

          __________________________________________________________
          11.9  Why do the keyboard arrow keys move the DECwindows cursor?

                   Congratulations, you have just stumbled into "dead
                   rodent" mode. This DECwindows environment-where the
                   keyboard arrow keys move the mouse cursor and where
                   the [SELECT], [PREV], and [NEXT] keys emulate the three
                   mouse buttons-allows rudimentary system operations when
                   the mouse is among the casualties.

                   To enter or exit "dead rodent" mode, enter the
                   following: <CTRL/SHIFT/F3>

          __________________________________________________________
          11.10  Why does half my DECwindows display blank?

                   This is likely a result of receiving an OPCOM or other
                   console message on a system that shares the system
                   console with the DECwindows graphics workstation
                   display.

                   You can toggle off the console display window using
                   <CTRL/F2> and you can enable a serial console per
                   Section 14.3.6 or Section 14.3.3.3.



                   11-14

 





                   DECwindows




                   Also see the console message window application
                   available with recent DECwindows versions-DECwindows
                   versions V1.2-3 and later will enable this window
                   by default. For details on this console message
                   window, see the DECW$CONSOLE_SELECTION option in
                   SYS$STARTUP:DECW$PRIVATE_APPS_SETUP.TEMPLATE.

                   On older releases, you can disable output using the
                   following:

                   $ SET TERMINAL/PERMANENT/NOBROADCAST OPA0:
                   $ DEFINE/USER SYS$COMMAND OPA0:
                   $ REPLY/DISABLE

                   Also see Section 14.3.3.2, Section 14.19, and Also see
                   Section 8.3,

          __________________________________________________________
          11.11  %DECW-W-NODEVICE, No graphics device found on this
                 system?

                   To resolve the following error:

                   %DECW-W-NODEVICE, No graphics device found on this system
                   -DECW-I-NODECW, DECwindows graphics drivers will not be loaded

                   o  Ensure that the system parameter WINDOW_SYSTEM is
                      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 1
                      WRITE ACTIVE
                      WRITE CURRENT
                      EXIT

                      Then reboot the system.

                   o  On OpenVMS Alpha, ensure the SYSMAN IO PREFIX LIST
                      is set correctly, and specifically ensure the DECW$
                      prefix is included in the existing list. If it is
                      not, you will need to add it:

                                                                     11-15

 





                   DECwindows




                      $ run sys$system:sysman
                      IO SHOW PREFIX
                      IO SET PREFIX=(DECW$,*)   * = list returned by the show command
                      IO AUTO/LOG
                      EXIT

                   o  Ensure that the image SYS$SHARE:DECW$ICBM.EXE is
                      installed in memory. If it is not installed, then
                      install it:

                      $ INSTALL LIST/FULL SYS$SHARE:DECW$ICBM
                      $ INSTALL REPLACE SYS$SHARE:DECW$ICBM
                      $ EDIT SYS$MANAGER:SYCONFIG.COM

                      $! The following line was added to install
                      $! support for the Mach64 Graphics Card
                      $!
                      $ INSTALL REPLACE SYS$SHARE:DECW$ICBM
                      $ ^Z

                      Then reboot the system.

                      The ICBM mechanism is not used on and not needed by
                      more recent DECwindows versions.

                   o  If the system still complains "%DECW-W-NODEVICE, No
                      graphics device found on this system", then:

                     o  Boot the system as normal

                     o  Login as SYSTEM.

                     o  Create the file SYS$COMMON:[SYSMGR]DECW$USER_
                        AUTOCONFIG.DAT. Protection must permit world read
                        access.

                     o  Add the following string on the very first line:

                         CLEAR_PFLAG = ISA_4BYTE

                     o  Save the file

                     o  Set the file protections

                         $ SET PROTECTION=W:RE SYS$MANAGER:DECW$USER_AUTOCONFIG.DAT

                     o  Reboot the system

                   Also see Section 11.5.

                   11-16

