|
See reader questions & answers on this topic! - Help others by sharing your knowledge
Archive-name: dec-faq/vms/part6
Posting-Frequency: quarterly
Last-modified: 02 Sep 2005
Version: VMSFAQ_20050902-06.TXT
DCL Details
DCL does not include support asynchronous I/O, thus a
predetermined protocol or a predetermined "turn-around"
command sequence must be implemented in order to avoid
protocol deadlocks-cases where both tasks are trying to
write or both tasks are trying to read. The task that
is writing messages to the network must write (or write
and read) a predetermined sequence of messages, or it
must write a message that tells the reader that it can
now start writing messages. (This is the essence of a
basic half-duplex network protocol scheme.)
__________________________________________________________
8.9 How can I get the width setting of a terminal?
$ width = f$getdvi(terminal,"DEVBUFSIZ")
__________________________________________________________
8.10 Why doesn't DCL symbol substitution work?
The DCL symbol substitution processing occurs only
at the DCL prompt, not within data and not within
files. If you wish to perform symbol substitution in
this environment, you typically write a small file
containing the command(s) and data to be invoked-
potentially only the data-and you then invoke the
created procedure or reference the specified data.
In this case, use of a file containing nolinemode
commands or other techniques might be useful-you will
want to ensure that the text editor you use does not
attempt to use screen mode or similar, as this is not
generally considered adventageous within a command
procedure.
Tools such as FTP have alternatives: COPY/FTP.
DCL symbol substitution occurs in two passes, using
the ampersand and the apostrophe. In most cases, only
the apostrophe is necessary. In a few cases-such as the
DCL PIPE command-you will may need to use the ampersand
to get the substitution to work. The following example
uses ampersand substitution to transfer the contents of
the header into a logical name:
$ PIPE CC/VERSION | (READ SYS$PIPE hdr ; DEFINE/JOB/NOLOG hdr &hdr )
8-9
DCL Details
A logical name (in the job logical name table; shared
by all processes in the current job) was used as DCL
symbols cannot be returned back out from a DCL PIPE or
other spawned subprocess.
For related materials, please see Section 8.1 and
Section 8.11.
__________________________________________________________
8.11 How can I substitute symbols in a PIPE?
Use DCL ampersand substitution, and not apostrophe
substitution.
$ pipe show system | search sys$input opcom | (read sys$input pid ;
pid=f$element(0," ",pid) ; define/system opcom_pid &pid)
$ show log opcom_pid
"OPCOM_PID" = "0000020B" (LNM$SYSTEM_TABLE)
__________________________________________________________
8.12 Use of RUN/DETACH, LOGINOUT, and logical names?
With a command to create a detached process such as:
$ RUN/DETACHED SYS$SYSTEM:LOGINOUT /INPUT=TEMP_INPUT.COM
If you are trying to use a logical name as the /INPUT,
/OUTPUT or /ERROR on a RUN/DETACH command, then
you must translate the logical name specifications
to physical references before passing them, or the
definitions must reside in a logical name table that is
visible to the newly-created process.
Also note that LOGINOUT only creates the SYS$LOGIN,
SYS$LOGIN_DEVICE, and SYS$SCRATCH logical names if it
is processing a login that is based on the contents of
a SYSUAF record-without access to the associated SYSUAF
record, this information is not available to LOGINOUT.
(If you want to see these particular logical names
created, then please specify the /AUTHORIZE qualifier
on the RUN/DETACHED command.)
If you do not specify LOGINOUT as the image, then
there is no easy way to get these logical names. Also,
any logical names that are used in the target image
file specification must also be in a logical name
table accessible (by default) by the newly-created
8-10
DCL Details
detached process. Shared tables include the group (if
the process is in the same UIC group) and the system
table. (If the target process is to be in another UIC
group, a suitablly privileged user or application can
create the necessary logical name(s) directly in the
other group logical name table.)
When in doubt, create a short DCL command file as
input, and use a SHOW LOGICAL and similar commands
to examine the context. (And use physical device and
directory references on the RUN/DETACH of the LOGINOUT
image, when specifying this command file as /INPUT.)
Also remember to check both security auditing and
system accounting when troubleshooting problems with
the RUN/DETACH.
Also see Section 8.2.
__________________________________________________________
8.13 How to use escape and control characters in DCL?
To write a message and then the bell character, use:
$ bell[0,7] = 7
$ write sys$output "Hello''bell'"
To write blinking text, use:
$ esc[0,7] = 27
$ text = "Blinking Text"
$ write sys$output "''esc'[5m''text'''esc'[m"
Also see sections Section 11.6, Section 12.1.
8-11
_______________________________________________________
9 Files
__________________________________________________________
9.1 How can I undelete a file?
OpenVMS doesn't have an "undelete" function. However,
if you are quick to write-protect the disk or if you
can guarantee that no new files get created or existing
files extended, your data is still on the disk and
it may be possible to retrieve it. The FLORIAN tool
available from various websites can potentially recover
the file, see question Section 13.1 for pointers. Other
alternatives here include the DFU tool, available on
the OpenVMS Freeware CD-ROM distribution.
If you are setting up a user environment for yourself
or for others, it is quite easy to use DCL to intercept
the DELETE command, using a symbol:
$ DEL*ETE :== @SYS$LOGIN:MYDELETE.COM
The DELETE symbol will cause the procedure to
be invoked whenever the user enters the DELETE
command, and it can copy the file(s) to a "trashcan"
subdirectory before issuing a "real" DELETE on the
files. Other procedures can retrieve the file(s) from
the "trashcan" subdirectory, and can (and should) clean
out the "trashcan" as appropriate. (Realize that this
DELETE symbol can interfere with DELETE/GLOBAL and
other similar DCL commands.)
__________________________________________________________
9.2 Why does SHOW QUOTA give a different answer than DIR/SIZE?
DIRECTORY/SIZE doesn't take into account the size of
file headers which are charged to your quota. Also,
unless you use DIRECTORY/SIZE:ALL, you will see only
the "used" size of the file, not the allocated size
which is what gets charged against your quota. Also,
you may have files in other directories.
9-1
Files
$ DIRECTORY/SIZE=ALL/GRAND [username...]
Grand total of D1 directories, F1 files, B1/B2 blocks.
$ DIRECTORY/SIZZ=ALL/GRAND [-]username.DIR
Grand total of 1 directory, 1 file, B3/B4 blocks.
$ SHOW QUOTA
User [username] has B5 blocks used, B6 available
of B7 authorized and permitted overdraft of B8 blocks on disk
If the user has no files in other directories and
all file-headers are only 1 block, then the following
should apply:
B5=B2+B4+F1+1
If the diskquota has drifted out of synchronization,
then the system-manager can force a quota rebuild-due
to various factors, the quota file can potentially
drift from the actual use over time, and a periodic
rebuild can be performed at appropriate intervals.
Also be aware that the DIRECTORY/SIZE command can
report larger values than might otherwise be expected
when used to evaluate files and/or directories that
are alias links-such as the system roots on OpenVMS
system disks-as the command reports a total that
is cumulative over all of the files and directories
examined, without regard for which ones might be
alias entries and which are not. (In other words, a
DIRECTORY/SIZE of an entire OpenVMS system disk will
report a disk useage value larger than the (usually
more accurate) value reported by the SHOW DEVICE
command. This as a result of the alias entries linking
each SYS$SYSDEVICE:[SYSCOMMON]SYS*.DIR directory file
and the SYS$SYSDEVICE:[000000]VMS$COMMON.DIR file
together.)
__________________________________________________________
9.3 How do I make sure that my data is safely written to disk?
If your application must absolutely guarantee that
data is available, no matter what, there's really no
substitute for RMS Journaling and host- or controller-
based shadowing. However, you can achieve a good degree
of data integrity by issuing a SYS$FLUSH RMS call at
appropriate times (if you're using RMS, that is.) If
you're using a high-level language's I/O system, check
9-2
Files
that language's documentation to see if you can access
the RMS control blocks for the open file. In C you can
use fflush followed by fsync.
For details on disk bad block handling on MSCP and
on SCSI disk devices, please see Ask The Wizard (ATW)
topic (6926).
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.8.
__________________________________________________________
9.4 What are the limits on file specifications and directories?
A file specification has an aggregate maximum size of
255 characters (NAM$C_MAXRSS) at present, assuming
ODS-2 limits and traditional DCL process parsing
settings (SET PROCESS/PARSE_STYLE). The node and
device specification may be up to 255 characters each-
file name and file types may be up to 39 characters
each. File versions are from 1 through 32767, though
0 (latest version), -0 (oldest version) and -n (n'th
previous version) can be used in most contexts. A file
specification may not have more than 8 directories and
subdirectories or-with a rooted directory, two sets of
eight are possible-and while it is possible to create
subdirectories of greater depth, accessing them under
ODS-2 is somewhat problematic in most cases, and thus
should be avoided.
Under ODS-5 with extended DCL parsing (SET
PROCESS/PARSE_STYLE), the filename length limits
are up around 4,095 (NAML$C_MAXRSS) characters, and
directories can be around 255 levels deep.
Application developers should use OpenVMS-supplied
routines for parsing file specifications - this ensures
that changes in what is allowable will not tend to
break your application. Consider that various parts of
the file specification may contain quoted strings with
embedded spaces and other punctuation! Some routines
of interest are SYS$FILESCAN, SYS$PARSE and LIB$TRIM_
9-3
Files
FILESPEC. For further information, see the OpenVMS
Guide to File Applications.
Performance of larger directory files improves
(greatly) with OpenVMS V7.2 and later-operations on
directory files of 128 blocks and larger were rather
slower on earlier OpenVMS releases due to the smaller
size of the directory cache and due to the directory
I/O processing logic.
For fastest directory deletions, consider a reverse
deletion-delete from the last file in the directory to
the first. This reversal speeds the deletion operation
by avoiding unnecessary directory I/O operations as
the files are deleted. Tools such as the Freeware DFU
can be used for this purpose, as can various available
reverse-DELETE DCL command procedures.
Also see Section 5.44.
__________________________________________________________
9.5 What is the largest disk volume size OpenVMS can access?
One Terabyte (TB; 2**31 blocks of 2**9 bytes;
0x07FFFFFFF blocks). 255 volumes in a volume set.
The largest contiguous allocation possible for any
particular file is 0x03FFFFFFF blocks.
Prior to the release of V6.0, the OpenVMS file system
was limited to disk volumes of 8.38 GB (2**24 blocks,
16777216 blocks) or less.
On some systems, there are restrictions in the console
program that limit the size of the OpenVMS system disk.
Note that data disks are not affected by console
program limits. For example, all members of the
VAXstation 3100 series are limited to a system disk
to 1.073 GB or less due to the console, though larger
data disks are possible. This limit due to the SCSI
drivers used by and built into the console ROM to read
the OpenVMS bootstrap files, and these same drivers are
also used by OpenVMS to write the system crashdump.
9-4
Files
There are numerous discussions of this VAXstation
3100 in the comp.os.vms newsgroup archives. Please
use Google newsgroup search to search the archives for
further details, for discussions of the workarounds,
and for details of the potential for a simple failed
bootstrap and particularly for discussions of the
potential for severe system disk corruptions on
crashes.
Some SCSI disks with capacities larger than 8.58
gigabytes (GB) will require the use of an OpenVMS ECO
kit (eg: ALPSCSI04_062 or later; see Section 14.25
for details) for new SCSI device drivers. Failure to
use this ECO can cause "rounding errors" on the SCSI
disk device capacity-OpenVMS will not use nor display
the full capacity of the drive-and "%sysinit-e-error
mounting system device status equals 000008C4" (8C4
-> "%SYSTEM-?-FILESTRUCT, unsupported file structure
level") errors during bootstrap. (One workaround for
the bootstrap when the bitmap is located far into the
disk is the use of INIT/INDEX=BEGIN.) The problem here
involves the particular extensions and fields used for
larger capacity disks within the SCSI specifications
and within the various intepretations of same.
For ATA (IDE) disk drives:
o Versions of SYS$DQDRIVER *BEFORE* X-15 topped out at
8.455 GB.
Fixed drivers (equal or greater than "X-15") were
shipped in:
o OpenVMS Alpha V7.2-1, and later
o V7.2 UPDATE V1.0 ECO, and later
o V7.1-2 UPDATE V1.0 ECO, and later
o V7.1-2 UPDATE V3.0 ECO, and later
o The newer SYS$DQDRIVER driver operates to disks up
to 33 GB without (known) problems, and effectively
works with rather larger disks (up to circa 137
GB) but is known to report an incorrect number of
"cylinders" with disks above 33 GB.
9-5
Files
See Section 14.4.4.2 for additional ATA SYS$DQDRIVER
information.
Be aware that a known restriction in certain older
versions of the Alpha SRM Console prevents booting most
ATA (IDE) drives larger than 8.455 GB, depending on
exactly where the various files are located on the
volume. Updated SRM consoles for systems with SRM
and ATA (IDE) drive support are (will be) available.
(OpenVMS Engineering has successfully bootstrapped
20GB ATA (IDE) disks using the appropriate SRM console
version.)
Note
All disk-related 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; 1 GB =
1073741824.) bytes. Please see Section 14.25 for
details of the nomenclature and of the units.
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.
9-6
Files
Also see Section 14.13, Section 14.25.
__________________________________________________________
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
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 2.17.1, Section 14.25.
__________________________________________________________
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?
For information on CD and DVD optical media drives on
OpenVMS, please see Section 14.29. For information on
the creation of OpenVMS media and of OpenVMS bootable
media, a full step-by-step sequence is documented in
the OpenVMS Ask The Wizard topic (9820). An abbreviated
version of the sequence is included here.
9-7
Files
Recording (writing) of CD and DVD optical media
requires a recording or media mastering application
or tool, and both commercial and non-commercial
options are available. Please see CDRECORD (both non-
DVD and DVD versions are available, and at least one
commercial version is available), and also see DVDwrite
(commercial) or DVDRECORD (open source). A port of
CDRECORD is present in OpenVMS V7.3-1 and later.
o Acquire a comparatively recent SCSI-based or ATAPI
(IDE) CD-R or DVD-R/RW or DVD+R/RW drive. Older
drives can be very problematic, while newer drives
are readily available, and are cheap and very fast,
and tend to have better compliance with current
standards. Use of older drives is not recommended.
Related device requirements information is available
in Section 14.29.
o Get the most recent LDDRIVER available on the
Freeware, or activate and use the LD version latent
in OpenVMS Alpha V7.3-1 and V7.3-2 by loading the LD
command verb (look within SYS$MANAGER:CDRECORD.COM
for related details), or use the integrated LD found
in OpenVMS V8.2 and later.
In particular, you will want to use the current ECO
kit for LDDRIVER (as available), or the version of
LD distributed with V8.2. The OpenVMS V8.2 version
of LDDRIVER was also kitted on Freeware V7.0 as
LD071.
If you are not running OpenVMS V8.2, the specified
LD071 kit or later, or a current ECO with the
update, you will want to upgrade, or you will want
to use the DCL command:
SET FILE/CACHING_ATTRIBUTES=NO_CACHING
on the LD partition file. This is a workaround for an
incompatibility found between older LDDRIVER versions and the
XFC caching support.
As an alternative to LD and LDDRIVER, you can
acquire and load the VD64 package from the Freeware.
o Get CDRECORD or CDWRITE or other similar recording
tool.
9-8
Files
CDRECORD (part of CDRTOOLS), CDWRITE, and
DVDRECORD (part of DVDRTOOLS) packages
(DVDRECORD is a fork of CDRECORD) are freely
available, and versions of CDRECORD are
available on the Freeware V6.0 distribution. (
http://www.hp.com/go/openvms/freeware/ ) An OpenVMS
port of the cmcd CD audio ripper is also reportedly
available. http://www.amb.org/xmcd/
Versions of CDRECORD (non-DVD) are latent in OpenVMS
Alpha V7.3-1 and later. Commercial versions of
CDDRECORD-with DVD capabilities-are also available
for various platforms, and particularly a variant of
CDRECORD known as CDRECORD-ProDVD.
Beware the tool chosen: some versions and
configurations of CDRECORD can record DVD media,
as can the DVDRECORD package, as can the commercial
DVDwrite package. Many versions of CDRECORD cannot
record DVD media, including the version of CDRECORD
latent within OpenVMS and the version found on
Freeware V6.0; these versions cannot record DVD
media.
o Build the contents of the disk on the LD or VD64
device partition.
o Use the chosen recording tool to record the contents
of the LD or VD64 partition directly onto the
optical medium.
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. If you use a Windows-based tool, you
will want to specifically select its raw mode, image
mode, or block-copy mode, depending on the terminology
within the particular tool. The transfer mode and
selections is variously refered to as a disk-at-once
9-9
Files
(DAO) 2048-byte block ISO Mode 1 raw/image/block data
disk recording mode.
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, including OpenVMS ports of common open-
source tools made available by Dr. Eberhard Heuser-
Hofmann and various others. Commercial packages and
options are also available. Dr. Heuser-Hofmann has
DVDwrite , a commercial package which can record DVD
media. ( http://home.tiscali.de/dvd4openvms )
OpenVMS can read ODS-2, ODS-5, and ISO-9660 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. InfoServer
support also has very specific CD-R recording device
prerequisites, and these recording devices are no
longer generally available.
Packages related to the use of DVD archiving are also
available, see the multi-volume capabilities of the
DVDarchive/restore Freeware.
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/
9-10
Files
o http://www.tditx.com/~odsiso/
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/
Also see Section 9.7.2 for details on access to
recorded media on older CD-ROM drives.
_____________________________
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.
9-11
Files
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
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-12
Files
_____________________________
9.7.2 Use of RRD42 and other older (embossed-media) CD drives?
The RRD42 series SCSI CD-ROM drive is sufficiently old
that it can have problems processing CD-R and CD-RW
media. Other very old CD drives can have equivalent
media compatibility problems when attempting to read
(much) newer CD media and newer CD media technologies.
These older CD drives are generally intended for use
with the so-called embossed media, rather than with
non-embossed recorded (recordable) media now in common
circulation.
Please consider using a slightly-less-ancient CD-ROM
or CD-R or CD-RW drive when working with non-embossed
recorded CD media.
To paraphrase one knowledgable-though deliberately
nameless-storage engineer, "The RRD42 drive is just
past the drooling idiot stage".
_____________________________
9.7.3 Creating Bootable OpenVMS I64 CD or DVD Media?
SYS$SETBOOT?
If you are creating a bootable CD or DVD media for
use with OpenVMS I64, you will want to specify the
SYS$SETBOOT block size of 2048, and you will also want
a disk cluster factor that is a multiple of four via
INITIALIZE/CLUSTER=4 (or 8, or...), or you will want
to ensure that SYS$EFI.SYS and SYS$DIAGNOSTICS.SYS
are aligned to a multiple of four blocks; to a 2048
byte boundary. This alignment and this blocking is
only necessary for OpenVMS I64, and only when creating
optical media OpenVMS I64 for bootstraps.
The default 512-byte block setting used by SYS$SETBOOT
is the correct and expected value for traditional disk
bootstraps on OpenVMS I64 systems.
Once the boot files are loaded, OpenVMS I64 operates
with 512-byte blocks; as is the case with ATAPI disks
on OpenVMS Alpha, all application code will only see
512-byte blocks on optical media on OpenVMS I64.
9-13
Files
OpenVMS I64 V8.2 and later are expected to
have a version of SYS$SETBOOT that will flag a
misaligned SYS$EFI.SYS and (if present) a misaligned
SYS$DIAGNOSTICS.SYS file.
For information on SYS$SETBOOT and the SET BOOTBLOCK
command, please see Section 14.3.9 and see the
OpenVMS documentation. The purpose and intent of the
SYS$SETBOOT.EXE image and the SET BOOTBLOCK command
is analogous to the WRITEBOOT.EXE image on existing
OpenVMS VAX and OpenVMS Alpha systems.
For information on CD and DVD optical media drives
on OpenVMS, please see Section 14.29. For additional
related information on creating bootable OpenVMS media,
please see Ask The Wizard topic (9820).
__________________________________________________________
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.
9-14
Files
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, OpenLink Software (OpenLink Universal
Data Access), and Synergex.
The unixODBC package available at
http://www.unixodbc.org has variously been found to
operate on OpenVMS, as well.
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 or with the UPDATE kits, you are using
XFC.
9-15
Files
Another confusion: the XFC product version is and
remains V1.0 in all released configurations, please do
not confuse the internal XFC product version (displayed
by various commands) with the version number associated
with the various ECO kit(s). XFC V1.0 does not permit
volumes to enter full XFC caching, as displayed by the
"Vols in Full XFC mode" portion of the DCL command SHOW
MEMORY/CACHE output.
__________________________________________________________
9.11 RMS Sequential Files and Platform Portability?
When working with mixed platforms, you will want to
become familiar with the various RMS sequential record
formats, including Variable with Fixed Control (VFC),
stream, stream LF, and stream CR, among other record
formats.
Switching formats uses CONVERT/FDL or SET
FILE/ATTRIBUTES. The former converts files, the
latter resets attributes. Text editors tend to select
attributes when creating new files that may or may
not meet requirements. If the default attributes do
not match your requirements, create a stub file, SET
FILE/ATTR, then edit the existing file. (Most editors
will preserve attributes on an existing file.)
When working with Windows, stream is usually the best
choice for sequential file operations. Stream LF
is most commonly used with UNIX and C applications.
Windows and UNIX tend not to be able to directly read
files of "unexpected" sequential RMS record formats.
VFC is a common OpenVMS format, encoding the record
length into the record. It is this extra data that can
cause corruption-like problems when viewed without RMS;
either directly via $qio or via the file system API on
other operating system platforms. You will want to look
at the low-level record formats, and at the RMS and
the Files and Applications documentation in the OpenVMS
manuals.
9-16
Files
If transfering through other platforms, use of a
current version of Zip (with the "-Vv" or "-V" option)
and unzip, or use of a BACKUP saveset will contain
and maintain the RMS file and record attributes. (For
BACKUP and its own attributes requirements, see the
restoration tool.)
9-17
_______________________________________________________
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 distributinng to other customer sites, send your
10-1
OpenVMS Programming Information
request in a mail message addressed to product[-at-
sign-]hylndr.sqp.zko.dec.com, 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.22, please also see the Ask The Wizard topic
(1661), and for information on debugging an OpenVMS
application, please see topic (7552).
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.8.
__________________________________________________________
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.hp.com/go/openvms/freeware/
10-2
OpenVMS Programming Information
o http://www.google.com/
OpenVMS programming documentation, including the
numerous example programs found in recent versions of
the OpenVMS Programming Concepts manual, is available:
o http://www.hp.com/go/openvms/doc/
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, you can also locate answers, source
code examples and related discussions in the Natural
Language Search Assistant (AskQ) database:
o http://askq.compaq.com/ (Also see Section 1.2.1.1.)
In this area, you will find the source code of
programming examples for calls to many of the
OpenVMS system services (and from various programming
languages), including calls to core services
sys$getjpi[w], sys$getsyi[w] and sys$qio[w], as well
as source code examples for calls to many other system
services and run-time library routines, and examples of
10-3
OpenVMS Programming Information
one of the more difficult calling interfaces found on
OpenVMS systems, that of the smg$create_menu routine.
Arne Vajhøj has put together a collection of OpenVMS
example programs. It can be found at:
o ftp://ftp.hhs.dk/pub/vms/
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.8. and
via:
o http://www.hp.com/go/openvms/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.2.
10-4
OpenVMS Programming Information
__________________________________________________________
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.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, and see Section 10.22 for details of inner-
mode floating point requirements, of data alignment,
requirements for use of /NOSYSLIB, and other related
inner-mode programming details, and see Section 10.11
for image-related information.
__________________________________________________________
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
10-5
OpenVMS Programming Information
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
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.
10-6
OpenVMS Programming Information
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
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.4.
10-7
OpenVMS Programming Information
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.8.
__________________________________________________________
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
10-8
OpenVMS Programming Information
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.
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.8.
__________________________________________________________
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-9
OpenVMS Programming Information
__________________________________________________________
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:
#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
10-10
OpenVMS Programming Information
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
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/
10-11
OpenVMS Programming Information
__________________________________________________________
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.
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.
10-12
OpenVMS Programming Information
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.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-13
OpenVMS Programming Information
__________________________________________________________
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';
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:
10-14
OpenVMS Programming Information
!
! 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.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/
10-15
OpenVMS Programming Information
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.8.
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.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-16
OpenVMS Programming Information
Also see Section 10.28 for another related discussion
of the OpenVMS Debugger, and of a technique that uses
the SS$_DEBUG signal.
__________________________________________________________
10.20 Dealing with Endian-ness?
OpenVMS VAX, OpenVMS Alpha and OpenVMS I64 (as well
as all Microsoft Windows implementations) 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.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-17
OpenVMS Programming Information
__________________________________________________________
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.
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.)
10-18
OpenVMS Programming Information
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 Failure to specify the prefixing qualifier (on
certain and usually older versions of C) 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:
/PREFIX=ALL_ENTRIES
o Some VAX C programs erroneously write to the string
literals. By default, HP C does not allow the
constants to change.
/ASSUME=WRITABLE_STRING_LITERALS
o Enables sharing ("shr") of globals and of extern
variables. HP C sets externs as non-shareable
("noshr"), VAX C as "shr".
/SHARE_GLOBALS
10-19
OpenVMS Programming Information
o VAX C assumes common block model for external
linkages.
/EXTERN_MODE=COMMON_BLOCK
o 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.
/[NO]MEMBER_ALIGNMENT
o Enable all manner of useful compiler diagnostics:
/WARN=ENABLE=(LEVEL4,QUESTCODE)/STANDARD=PORT/ACCEPT=NOVAXC_KEYWORDS
You can disable extraneous diagnostics with the
following:
#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
10-20
---------------------------- #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
User Contributions: |
Comment about this article, ask questions, or add new information about this topic: