Search the FAQ Archives

3 - A - B - C - D - E - F - G - H - I - J - K - L - M
N - O - P - Q - R - S - T - U - V - W - X - Y - Z
faqs.org - Internet FAQ Archives

OpenVMS Frequently Asked Questions (FAQ), Part 6/11

( Part1 - Part2 - Part3 - Part4 - Part5 - Part6 - Part7 - Part8 - Part9 - Part10 - Part11 )
[ Usenet FAQs | Web FAQs | Documents | RFC Index | Counties ]

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:

CAPTCHA




Part1 - Part2 - Part3 - Part4 - Part5 - Part6 - Part7 - Part8 - Part9 - Part10 - Part11

[ Usenet FAQs | Web FAQs | Documents | RFC Index ]

Send corrections/additions to the FAQ Maintainer:
hoff@hp.nospam





Last Update March 27 2014 @ 02:11 PM