Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!newsfeed.stanford.edu!cyclone.bc.net!news-hog.berkeley.edu!ucberkeley!nntp-relay.ihug.net!ihug.co.nz!news.compaq.com!news.cpqcorp.net!53ab2750!not-for-mail

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!newsfeed.stanford.edu!cyclone.bc.net!news-hog.berkeley.edu!ucberkeley!nntp-relay.ihug.net!ihug.co.nz!news.compaq.com!news.cpqcorp.net!53ab2750!not-for-mail
Newsgroups: comp.os.vms,comp.sys.dec,vmsnet.alpha,vmsnet.misc,comp.answers,news.
Distribution: world
X-Newsreader: mxrn 6.18-32C
Expires: 03 Jul 2004 00:00:00 GMT
Followup-To: poster
References: <[email protected]>
Approved: [email protected]
From: [email protected] (Hoff Hoffman)
Reply-To: [email protected]
Organization: HP
Subject: OpenVMS Frequently Asked Questions (FAQ), Part 5/9
Summary: This posting contains answers to frequently asked questions about
the OpenVMS operating system from HP, and the computer systems on
which it runs.
Lines: 2364
Message-ID: <[email protected]>
Date: Thu, 03 Jul 2003 17:14:04 GMT
NNTP-Posting-Host: 16.32.80.251
X-Complaints-To: [email protected]
X-Trace: news.cpqcorp.net 1057252444 16.32.80.251 (Thu, 03 Jul 2003 10:14:04 PDT)
NNTP-Posting-Date: Thu, 03 Jul 2003 10:14:04 PDT
Xref: senator-bedfellow.mit.edu comp.os.vms:389891 comp.sys.dec:98153 vmsnet.alpha:12770 vmsnet.misc:6469 comp.answers:54091

Files

NOTE: All ATA-related disk sizes listed in this section
are stated in units of "disk (base ten) gigabytes" (1
GB = 10^9 bytes) and NOT in units of "software (base
two) gigabytes" (1 GB = 2^30 (1073741824.) bytes. See
Section 14.26.

Be aware that larger disks that are using an extension
of SCSI-2- disks that are using a mode page field
that the SCSI-2 specifications normally reserved for
tape devices-to permit a larger disk volume size will
require a SCSI driver update for OpenVMS, and this
change is part of V7.1-2 and later, and also part of
ALPSCSI07_062 and later. (These larger disks disks
will typically report a DRVERR, or will see the volume
size "rounded down".) SCSI disks larger than 16777216
blocks cira 8.455 GB (base ten); 8GB (base two) require
this ECO, or require the use of OpenVMS Alpha V7.1-2 or
later.

Applications written in C can be limited to file
sizes of two gigabytes and less, as a result of the
use of longword values within C file operations, and
specifically off_t. This restriction is lifted in
OpenVMS V7.3-1 and later, and with the application of
the C ECO kits available for specific earlier 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.

Also see Section 14.14, Section 14.26.

__________________________________________________________
9.6 What is the maximum file size, and the RMS record size
limit?

RMS can store individual files of a size up to the
maximum supported volume size. Under OpenVMS V6.0 and
later, the volume size and the RMS maximum file size
limit is 2**31 * 512 bytes-one terabyte (1 TB).

"Use a volume set to provide a large, homogeneous
public file space. You must use a volume set to create
files that are larger than a single physical disk
volume. (The file system attempts to balance the load

9-6

Files

on the volume sets, for example, by creating new files
on the volume that is the least full at the time.)"

"You can add volumes to an existing volume set at any
time. The maximum number of volumes in a volume set is
255."

The RMS formats-sequential, relative, and indexed-
are limited by the one terabyte maximum volume size.
RMS relative files are further limited to a number of
records that will fit in 32 bits-4 billion records.
Sequential and indexed formats do not have a record
limit.

Also see Section 10.14, Section 14.26.

__________________________________________________________
9.7 How do I write CD-Recordable or DVD media on OpenVMS?

How to create CD-R, CD-RW, DVD-R, DVD+R, DVD-RW, or
DVD+RW media on OpenVMS?

o Acquire a comparatively recent SCSI-based or ATA
(IDE) CD-R or DVD-R/RW or DVD+R/RW drive. Older
drives can be problematic, while newer drives are
readily available, cheap and very fast.

o Get LDDRIVER from the Freeware. Versions of LDDRIVER
are latent in OpenVMS Alpha V7.3-1 and later. (Look
within SYS$MANAGER:CDRECORD.COM for details.)

o Get CDRECORD or CDWRITE or other similar recording
tool. (CDRECORD and CDWRITE are freely available,
though versions are not on the Freeware V5.0
distribition; the URLs are referenced later in this
section). Versions of CDRECORD are latent in OpenVMS
Alpha V7.3-1 and later.

o Build the contents of the disk on the LD device
partition.

o Use the CDRECORD or CDWRITE or other tool to record
the contents of the LD partition directly onto the
CD-R or CD-RW media.

9-7

Files

Alternatively, consider the following command on
OpenVMS Alpha V7.3-1 and later:

@SYS$MANAGER:CDRECORD.COM HELP

While folks have had success getting PC-based CD-R/RW
or DVD-R/RW or DVD+R/RW tools to work with OpenVMS
partitions, it is far easier and more reliable to use
the OpenVMS-based versions of these tools and directly-
attached devices.

More details: Creation of CD recordable or DVD
recordable media under OpenVMS typically involves
one of two approaches: the use of the optional CD-R
(`Scribe') capabilities available for the InfoServer or
other "offline" hardware packages (PC-based packages
will be included in this), or the use of a host-based
package such as the CDRECORD or CDWRITE13_VMS or other
utilities, OpenVMS ports of common open-source tools
made available by Dr. Eberhard Heuser-Hofmann and
others.

OpenVMS can read ODS-2, ODS-5, and ISO-9960 format
CD-ROMs. (If you are very careful, you can create a
dual-format CD-R; a CD-R with both ODS-2 and ISO-9660
or both ODS-5 and ISO-9660 or both.)

InfoServer hardware configurations are no longer
available from HP, but may potentially be acquired
through other means; as used equipment.

http://www.geocities.com/SiliconValley/Lakes/9999/vmscdwri.html

Additional information is available at the following
sites:

o http://www.djesys.com/vms/cdrom.html

o http://www.cd-info.com/CDIC/Technology/CD-R/vms.html

o http://www.faqs.org/faqs/cdrom/cd-
recordable/part1/preamble.html

o http://www.tmesis.com/CDrom/

o http://www.tditx.com/~odsiso/

9-8

Files

U.S. Design offers a package that includes the tools
necessary to create a CD or DVD-R with either ISO-9660
or ODS-2 format, for standalone CD-R/RW, DVD-R, or
DVD+R/RW drives, for recent OpenVMS versions. Details
are available at:

o http://www.usdesign.com/

_____________________________
9.7.1 CD and DVD notation, terminology?

CD-ROM is pre-recorded Compact Disk media, and is
the original and oldest CD format. The original CD
media was physically stamped, a recording process that
is now largely reserved to the highest-volume media
reproduction requirements.

CD-R is CD Recordable, a write-once storage medium
that can be read by all but the oldest of CD drives;
a format which can be read and often even recorded by
most CD-RW drives.

CD-RW is CD ReWritable, a format which is readable by
many CD drives and by most CD-R drives, and with media
that can be recorded and re-recorded by CD-RW drives.

CD media recording speeds are listed as multiples of
150 kilobytes per second, so a 10X drive records at
1500 kilobytes (1.5 megabytes) per second. 600 MB (70
minutes) and 700 MB (80 minutes) recording capacities
are both widely available. The minutes designation is
derived from the traditional audio-format recording
capacity of the particular media.

DVD-R/RW is the older of two common Digital Versatile
Disk recording formats, and the DVD-R Recordable or
DVD-RW ReWritable media can be read by many DVD drives.
As with CD-R formats in older CD drives, older DVD
and particularly first-generation DVD players may have
problems reading this media format.

DVD+R/RW is the newer of the two common Digital
Versatile Disk recording formats, and the DVD+R
Recordable or DVD+RW ReWritable media can be read
by many DVD drives. Akin to DVD-R/RW media, older

9-9

Files

and particularly first-generation DVD drives can have
problems reading this media format.

The DVD Plus-series drives and media tend to record
faster than Minus drives, as (as of this writing)
the Plus (+) drives do not require an initial media
formatting pass and the Minus (-) drives do. While the
appropriate Plus (+) or Minus (-) DVD raw media must
be chosen for the particular DVD recorder (and DVD
recording drives that are compatible with and capable
of using both Plus and Minus media are available),
the resulting recorded media is generally readable
(playable) in all recent DVD drives and DVD players,
regardless of type. (Compatibility is best within the
same media-series devices of course, but be certain
to verify compatibility across devices regardless of
the particular device or particular recording media
chosen.)

Presently Plus (+) media is slightly more expensive
than Minus (-), but with the prices of all CD and
all DVD media continuing to consistently fall, the
differences in DVD media costs are becoming irrelevent
for all but the production of huge volumes of DVD
media.

The rated DVD recording speeds are in multiples of 1353
kilobytes per second, thus a DVD 1X drive is roughly
equivalent to a CD 9X drive in I/O requirements and
transfer speed.

DVD drive recording speed can and does vary. DVD disk
drive recording speed is limited by the rated recording
speed of the media used, so the slower (and cheaper)
DVD media will not record any more quickly in a faster
drive. A 2.4X DVD drive loaded with 1X media will
record at 1X.

9-10

Files

__________________________________________________________
9.8 What I/O transfer size limits exist in OpenVMS?

The maximum transfer size is an attribute of the
particular I/O device, controller and driver
combination; there is no inherent limit imposed by
OpenVMS (other than the fact that, today, byte counts
and LBNs are generally limited to 32 bits).

The maximum size of a device I/O request is limited
by the value in UCB$L_MAXBCNT, which is set by the
device driver based on various factors. (Also check the
setting of the MAXBUF system parameter for buffered I/O
transfers, and check the process quotas.)

Currently, SCSI drivers limit I/O transfers to FE00(16)
bytes, 65024 bytes (decimal). The reasons for this
transfer size limitation are largely historical.
Similarly, DSSI devices are limited to the same value,
this for hardware-specific reasons. Transfers to HSC
and HSJ device controllers via the CI are limited
to 1,048,576 bytes. Client MSCP-served devices are
limited to 65535 bytes-to help ensure that the I/O
fragmentation processing happens on the client and not
on the server system.

Parts of the OpenVMS I/O subsystem are optimized for
data transfers less than 64KB, because (obviously)
most I/O operations are (substantially) less than that.
OpenVMS can handle larger transfers, if the driver and
the device can handle it.

Also see Section 9.4, Section 9.5.

__________________________________________________________
9.9 Can I use ODBC to connect to OpenVMS database files?

Yes, you can use various available third-party packages
that permit remote ODBC clients to access RMS files and
various commercial databases via the network.

For RMS, consider acquiring one of the packages
available from EasySoft, Attunity Connect (formerly
known as ISG Navigator), Oracle (DB Integrator),
SolutionsIQ, and Synergex.

9-11

Files

For specific commercial databases (other than RMS,
of course), contact the database vendor directly for
assistance.

__________________________________________________________
9.10 If my disks are shown as VIOC Compatible, am I using XFC?

Yes, you are using XFC caching.

Disks that are using XFC caching use communication and
coordination protocols that are compatible with the
older VIOC caching implementation. With the initial
implementation of XFC on OpenVMS, you can use the
command SHOW MEMORY/CACHE to see no disks reported
in full XFC mode; all disks shown will be listed in
VIOC Compatable Mode.

If you have the OpenVMS system parameter VCC_FLAGS set
to 2 and are using OpenVMS Alpha V7.3-1 or later, or
are using OpenVMS Alpha V7.3 with the VMS73_XFC V2.0
ECO kit or later, you are using XFC.

9-12

_______________________________________________________

10 OpenVMS Programming Information

__________________________________________________________
10.1 Modular Programming, Facility Prefixes and Symbol Naming?

Please first review the OpenVMS Programming Concepts
Manual and the Guide to Modular Programming manuals.
Both are available within the OpenVMS documentation
set, and provide details of the expected norms for
OpenVMS programs.

o Learn about the facility prefix, and use a the
appropriate prefix uniformly throughout all external
symbols, all logical names, and all files located
in shared directories. The prefix and the use of
the dollar sign (<$>) and the underscore (<_>) help
avoid collisions with other products. Use of the
dollar sign is reserved to registered products.

o Please consider use of tools such as the Freeware
SDL package, and the GNM package. These permit you
to generate include files and message documentation
akin to that of OpenVMS, providing users of your
product with a familiar environment.

o For product installations, consider use of the PCSI
installation utility, and provide a product-specific
configuration DCL command procedure (usually
SYS$MANAGER:prefix$CONFIG.COM) if configuration
is required.

o The product startup file is usually named
SYS$STARTUP:prefix$STARTUP.COM, and the
shutdown file (if needed) is usually
SYS$STARTUP:prefix$SHUTDOWN.COM.

OpenVMS provides a registry for facility prefixes
and for MESSAGE message compiler codes. To request
a prefix and a message facility code for a product
you are reselling, send your request in a mail message
addressed to product[-at-sign-]hylndr.sqp.zko.dec.com,

10-1

OpenVMS Programming Information

requesting the submission form and details of the
registration process.

Note

Please do not request facility prefixes for
products that local to your business, your
site, or your system. Facility prefixes and
message codes and the facility registration
process are intended solely for HP products
and Partner Products (and yes, even OpenVMS
Freeware packages) that will be distributed
across multiple OpenVMS customer sites.

For a list of common coding bugs, please see the
remainder of this section of the FAQ and specifically
Section 10.24, please also see the Ask The Wizard topic
(1661), and for information on debugging an OpenVMS
application, please see topic (7552).

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

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, please see Section 3.9.

__________________________________________________________
10.2 Can I have a source code example of calling...?

Please use the available SEARCH command on OpenVMS, and
please remember to search the available resources,
including the support databases and the newsgroup
archives. Please also realize that most OpenVMS system
services use similar calling sequences, meaning that an
example of calling sys$getjpi can be used as an example
for sys$getsyi and sys$getdvi. Students: please do not
expect folks to write your homework for you. As for
search resources:

o SEARCH SYS$EXAMPLES:*.* target

o SEARCH TCPIP$EXAMPLES:*.* target

o http://askq.compaq.com/

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

o http://www.google.com/

10-2

OpenVMS Programming Information

OpenVMS programming documentation, including the
numerous example programs found in recent versions of
the OpenVMS Programming Concepts manual, is available:

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

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

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

As for details of argument passing, most OpenVMS system
services and RTL routines pass string arguments by
descriptor. Languages which support native string
data types create descriptors automatically; those
which do not (eg., C) require that you set them up
explicitly. For further details on using descriptors
and particularly for using descriptors from C, please
see Section 10.13.

There is extensive information available on how to call
OpenVMS system services and OpenVMS Run-Time Library
routines, including examples in numerous languages.
Among the best available references are:

o Your language's User Manual

o OpenVMS Programming Environment Manual

o OpenVMS Programming Concepts Manual

o OpenVMS Programming Interfaces: Calling a System
Routine

o OpenVMS Calling Standard

In addition, if you are a subscriber to the HP Software
Information Network (available to those with a software
support contract), the support database contains
hundreds of worked examples of calling system services
and RTL routines, including the one that seems to trip
up almost everyone, SMG$CREATE_MENU.

Arne Vajh�j has put together a collection of OpenVMS
example programs. It can be found at:

o ftp://ftp.hhs.dk/pub/vms/

10-3

OpenVMS Programming Information

Additional information and examples for OpenVMS are
available via:

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

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, 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.12.

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.openvms.compaq.com/wizard/

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, 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.openvms.compaq.com/wizard/

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, 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 many bytes are in a disk block?

A disk block is the minimum unit of disk storage
allocation in OpenVMS.

Under OpenVMS VAX and OpenVMS Alpha, the disk volume
block size is consistent, with each block containing
512 bytes.

The minimum disk allocation granularity actually
permissible (in the ODS-2 and ODS-5 volume structures
commonly used on OpenVMS) is determined on a per-volume
basis, and is typically based on a combination of the
total number blocks on the disk volume and the total
size of the volume storage bitmap. The allocation
granularity is known as the volume cluster factor-
the cluster factor is the number of blocks in a disk
cluster, and it is the smallest number of blocks that
can be allocated on a particular disk volume.

10-11

OpenVMS Programming Information

Prior to OpenVMS V7.2, the maximum permissible size of
the bitmap requires larger cluster factors as volume
sizes increase. Starting with V7.2, the bitmap can be
larger, and cluster factors as small as one block can
be used.

The number of bytes in a file can be determined by
multiplying the number of blocks allocated for the file
times the number of bytes in a block. For sequential
files (only), the FFB (XAB$W_FFB, in the File Header
XAB) value can be used to find out how much of the
last (XAB$L_EBK) block is used. FFB and EBK are
meaningful only for sequential files, and only in
a limited context-partial block allocations are not
permitted. For other file formats, the EOF marker is
not meaningful.

Disk allocations always occur only in units of the
cluster factors, which can be from one block up to
(potentially) clusters of eighteen blocks or more,
depending on the volume cluster factor. (OpenVMS V7.2
and later optionally provide for a cluster factor of
one up to volumes of approximately 137 gigabytes.)

OpenVMS assumes that the device driver and the
underlying storage device will present the file system
with addressable units of storage of 512 bytes in size,
or the appearance of same. Various third-party CD-ROM
devices, for instance, support only 2048 byte blocks,
and such devices are incompatible with the standard
OpenVMS device drivers.

To determine the number of bytes required for a file
from DCL, one option uses the f$file_attributes item
EOF, multiplied by the size of a block in bytes (512).
This does not account for the unused space in the last
block of a sequential file, but it also does not have
to differentiate sequential files from other files.

10-12

OpenVMS Programming Information

__________________________________________________________
10.15 How many bytes are in a memory page?

A memory page is the minimum unit of memory allocation
in OpenVMS. With OpenVMS VAX, the memory page size
matches the disk block size: it is always 512 bytes.

With OpenVMS Alpha, the memory page size is variable,
and it can range from 8192 bytes (8 kilobytes) up
to 64 kilobytes. The current system page size can be
determined using the sys$getsyi or f$getsyi PAGE_SIZE
item. Programs with hardcoded constants for the memory
page size (or page alignment) should always assume a
page size of 64 kilobytes.

On OpenVMS Alpha, a 512 byte area of memory-equivilent
in size to an OpenVMS VAX memory page-is refered to as
a pagelet.

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

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

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

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

10-13

OpenVMS Programming Information

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.17 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

10-14

OpenVMS Programming Information

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.18 Where can I obtain Bliss, and the libraries and
supporting files?

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

Bliss language source code that contains the following
statement:

LIBRARY 'SYS$LIBRARY:STARLET.L32';

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

STARLET.L32 contains the public interfaces to OpenVMS:

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

10-15

OpenVMS Programming Information

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

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

The equivilent files for Bliss64 are created with:

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

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

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

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

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

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

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

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

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

10-16

OpenVMS Programming Information

__________________________________________________________
10.19 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.openvms.compaq.com/wizard/

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, 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.20 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.21 How do I activate the OpenVMS Debugger from an
application?

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

10-17

OpenVMS Programming Information

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.22 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-18

OpenVMS Programming Information

__________________________________________________________
10.23 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.24 Compaq 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-19

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-20

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.

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.

10-21

OpenVMS Programming Information

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.openvms.compaq.com/wizard/

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, please see Section 3.9.

_____________________________
10.24.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

10-22

OpenVMS Programming Information

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.4.)

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
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).

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

10-23

OpenVMS Programming Information

...
#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.24.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.17 for information on the C system and
the lib$spawn call in CAPTIVE environments.

10-24

OpenVMS Programming Information

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.

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.

10-25

OpenVMS Programming Information

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.

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

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

o http://www.openvms.compaq.com/wizard/wizard.zip

For additional information, 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.25 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.

10-26

OpenVMS Programming Information

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

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.15 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.15.

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.openvms.compaq.com/freeware/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 does the DELETE key delete forward instead of
backward?

This 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-4

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.

__________________________________________________________
11.6 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

11-5

DECwindows

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

o PowerStorm 350

o ELSA GLoria Synergy

o 3DLabs Oxygen VX1

See Section 5.15 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.

11-6

---------------------------- #include <rtfaq.h> -----------------------------
For additional, please see the OpenVMS FAQ -- www.hp.com/go/openvms/faq
--------------------------- pure personal opinion ---------------------------
Hoff (Stephen) Hoffman OpenVMS Engineering hoff[at]hp.com