# From: hoffman@xdelta.zko.dec.nospam & Sent: Friday, January 07, 2000 9:51 PM To: Info-VAX@Mvb.Saic.Com ; Subject: OpenVMS Frequently Asked Questions (FAQ), Part 3/4        Archive-name: dec-faq/vms/part3  Posting-Frequency: monthly Last-modified: 7 January 2000  Version: VMS-FAQ-3.TXT(3)    Overview ========E This is part 3/4 of the Frequently Asked Questions (FAQ) posting for  < the comp.os.vms and vmsnet.misc newsgroups.  (comp.os.vms isC bidirectionally-gatewayed to the INFO-VAX mailing list - see INTRO3 > for further details.)  It contains answers to frequently askedB questions about Compaq's OpenVMS operating system and the computer> systems on which it runs.  (Please see INTRO5 before posting.)  9   The OpenVMS FAQ is archived in the following locations:   :     http://www.openvms.digital.com/wizard/openvms_faq.html9     ftp://ftp.digital.com/pub/Digital/dec-faq/OpenVMS.txt 1     ftp://ftp.digital.com/pub/Digital/dec-faq/vms :     ftp://rtfm.mit.edu/pub/usenet/news.answers/dec-faq/vms,     comp.answers and news.answers newsgroups  A   Other internet FAQs are generally available in these locations:   ,     comp.answers and news.answers newsgroups%     ftp://rtfm.mit.edu/pub/usenet/...   ?   User-created HTML versions of the OpenVMS FAQ are located at:        http://www.kjsl.com/vmsfaq'     http://eisner.decus.org/vms/faq.htm   H Please do NOT send technical questions to the Frequently Asked QuestionsH (FAQ) editor -- well, please do not email any questions that do not alsoF include the answer(s).  Please post these questions to the appropriateH newsgroup instead -- and see INTRO5 before posting.  To make suggestionsF for changes or additions to this FAQ list, please send mail to the FAQH editor at hoffman@xdelta.zko.dec.com.  Again, the FAQ editor is *not* in' a position to answer general questions.    Some general notes:   K The term "VMS" is synonymous with "OpenVMS".  "Alpha", "AlphaGeneration" or F "AXP" generally refers to any system or product based on or related toJ Compaq's Alpha processor architecture.  OpenVMS manual names mentioned areC those as of V7.2 -- names may be different in other editions of the  documentation set.  H World-Wide Web Universal Resource Locator (URL) notation is used for FTP
 addresses.  F Many people have contributed to this list, directly or indirectly.  InG some cases, an answer has been adapted from one or more postings on the D comp.os.vms newsgroup.  Our thanks to all of those who post answers.H The name (or names) at the end of an entry indicate that the informationD was taken from postings by those individuals; the text may have beenG edited for this FAQ.  These citations are only given to acknowledge the 
 contribution.   A Although the editor of this FAQ is an employee of Compaq Computer A Corporation, this posting is not an official statement of Compaq.   L AlphaGeneration, AlphaServer, AlphaStation, Alpha AXP, AXP, DEC, DECstation,I DECsystem, OpenVMS, ULTRIX, VAX and VMS are trademarks of Compaq.  Compaq L and the names of Compaq products are trademarks and/or registered trademarksK and/or service marks of Compaq Computer Corporation.  OSF/1 is a registered J trademark of the Open Software Foundation.  UNIX is a registered trademarkF in the United States and other countries, licensed exclusively throughK X/Open Company Ltd.  Other names are properties of their respective owners.    Table of Contents - Part 3/4 ____________________________   Other Utilities ( ========================================4 UTIL1.  How do I play an audio CD on my workstation?: UTIL2.  How do I access a MS-DOS floppy disk from OpenVMS?L UTIL3.  How do I play sound files on an AlphaStation?  DECsound doesn't work   DCL and command usage ( ========================================. DCL1.   How do I run a program with arguments?/ DCL2.   How can I redefine control keys in DCL? * DCL3.   How can I clear the screen in DCL?2 DCL4.   How do I do a REPLY/LOG in a batch stream?1 DCL5.   How do I generate a random number in DCL? % DCL6.   What does the MCR command do? 2 DCL7.   How do I change the OpenVMS system prompt?< DCL8.   Can I do DECnet task-to-task communication with DCL?   File System and RMS ( ========================================" FILE1.  How can I undelete a file?B FILE2.  Why does SHOW QUOTA give a different answer than DIR/SIZE?B FILE3.  How do I make sure that my data is safely written to disk?C FILE4.  What are the limits on file specifications and directories? @ FILE5.  What is the largest disk volume size OpenVMS can access?E FILE6.  What is the maximum file size, and the RMS record size limit? = FILE7.  How do I write recordable CD media (CD-R) on OpenVMS? 7 FILE8.  What I/O transfer size limits exist in OpenVMS?    Programming ( ========================================: PROG1.  How do I call <routine_name> from <language_name>?9 PROG2.  How do I get the arguments from the command line? = PROG3.  How do I get a formatted error message in a variable? D PROG4.  How do I link against SYS$SYSTEM:SYS.STB on an Alpha system?8 PROG5.  How do I do a SET DEFAULT from inside a program?M PROG6.  How do I create a shareable image transfer vector on an Alpha system? H PROG7.  How do I turn my Fortran COMMON into a shareable image on Alpha?< PROG8.  How do I convert between IEEE and VAX floating data?= PROG9.  How do I get the argument count in a Fortran routine? ? PROG10. How do I get a unique system ID for licensing purposes? ? PROG11. What is an executable, shareable, system or UWSS image? / PROG12. How do I do a file copy from a program?  PROG13. What is a descriptor? + PROG14. How many bytes are in a disk block? , PROG15. How many bytes are in a memory page?9 PROG16. How do I create a process under another username? D PROG17. Why do lib$spawn, lib$set_symbol fail in detached processes?I PROG18. Where can I obtain Bliss, and the libraries and supporting files? 0 PROG19. How can I open a file for shared access?  < ------------------------------------------------------------4 UTIL1.  How do I play an audio CD on my workstation?  8 If you've installed the DECwindows examples, you'll findD DECW$CDPLAYER.C, .DAT, .EXE, .UIL, and .UID.  Copy the .UID and .DATL files to DECW$USER_DEFAULTS: (typically SYS$LOGIN:), define the logical nameH DECW$CD_PLAYER to be the device name of your CD-ROM drive (eg. DKA400:),H give yourself PHY_IO and DIAGNOSE privileges, and run the .EXE.  You canA also install the image with these privileges.  See the source for B additional details - note that the comments regarding the need forD SYSGEN CONNECT are no longer applicable (at least as of VMS V5.5-2).  F There's also SYS$EXAMPLES:CDROM_AUDIO.C and .EXE, a non-Motif program.  < ------------------------------------------------------------: UTIL2.  How do I access a MS-DOS floppy disk from OpenVMS?  E The Compaq Advanced Server (formerly known as PATHWORKS) for OpenVMS  G product includes an unsupported and undocumented utility called PCDISK, A and this tool can read and write various MS-DOS format diskettes.   H ProGIS in Germany sells a product called VMove which supports DOS files C on many different device types.  For more information, send mail to  info@progis.rmi.de.   H Engineering Software has a product called VAKSAT which will read, write,D and erase files on DOS diskettes.  Available for both VAX and Alpha.0 Contact ed@cityscape.co.uk for more information.  D MadGoat PC Exchange (PCX) is a utility for copying files to and fromE MS-DOS format diskettes under VMS, using an RX23 (3.5"), RX26 (3.5"), A or RX33 (5.25") diskette drive.  For 3.5" diskettes, high-density F disks can be read or written; double-density disks are read-only. Only- high-density disks are supported on the RX33.      http://www.madgoat.com/   < ------------------------------------------------------------L UTIL3.  How do I play sound files on an AlphaStation?  DECsound doesn't work  I The new AlphaStation systems use a different sound board (Microsoft Sound K System) than the earlier DEC 3000 AXP systems, and DECsound, as supplied by H DECwindows Motif, doesn't support this board.  Compaq offers an optional) product, Multimedia Services for OpenVMS:   %   http://www.digital.com/info/SP6424/    J which provides a replacement DECsound for this card as well as many other > features (an AVI and MPEG player, video capture support, etc.)  B Ensoniq sound support is expected to be available in January 2000.  < ------------------------------------------------------------. DCL1.   How do I run a program with arguments?  K The RUN command does not accept arguments.  To pass arguments to a program, > you must use what is called a "foreign command".  For example:  ' 	$ uudecode :== $disk:[dir]uudecode.exe  	$ uudecode filespec  M The leading $ in the symbol definition is what makes it a foreign command. If > the device and directory is omitted, SYS$SYSTEM: is assumed.    D Under OpenVMS V6.2 and later, DCL supports automatic foreign commandN definition via the logical name DCL$PATH:.  An example of a definition of this logical name is:  >     $ DEFINE DCL$PATH SYS$DISK:[],ddcu:[mytooldir],SYS$SYSTEM:  N DCL will first look for a command in the DCL command table, and if no match isN found and if DCL$PATH is defined, it will then look for command procedures andG executable images with filenames matching the command specified, in the J directories specified via DCL$PATH.  The first match found is invoked, andH under OpenVMS, the DCL$PATH support will cause a command procedure to be/ activated in preference to an executable image.   H For more information on foreign commands or on automatic foreign command' support, see the OpenVMS User's Manual.    See also question PROG2.  L If you want to create a detached process that takes arguments from a commandJ line, it must be run under the control of a command line interpreter (CLI)E (typically DCL).  This is done by placing the command line in a file, N specifying SYS$SYSTEM:LOGINOUT.EXE as the image to run and the command file as the input.  For example:    	$ OPEN/WRITE CMD TEMP_INPUT.COM$ 	$ WRITE CMD "$ MYCOMMAND arguments" 	$ CLOSE CMD9 	$ RUN/DETACHED SYS$SYSTEM:LOGINOUT /INPUT=TEMP_INPUT.COM   N Various OpenVMS library calls (such as lib$spawn(), cli$dcl_parse(), and the CK library system() call) require access to a command line interpreter such as F DCL to perform requested actions, and will not operate if a CLI is not
 available.  J When a CLI is not available, these calls typically return the error statusL SS$_NOCLI.  And as mentioned above, invoke the image LOGINOUT to cause a CLIH (such as DCL) to be mapped into and made available in the context of the target process.  					[Stephen Hoffman]  < ------------------------------------------------------------/ DCL2.   How can I redefine control keys in DCL?   C The DCL DEFINE/KEY command allows you to define function and keypad F keys, but not control keys.  Also, keys you define with DEFINE/KEY areD not recognized inside applications.  Many applications which use the: SMG$ routines for input have a similar DEFINE/KEY feature.  G The terminal driver line-editing control keys, including the use of DEL  for delete, are not modifiable.   < ------------------------------------------------------------* DCL3.   How can I clear the screen in DCL?  0 The simplest way is the TYPE/PAGE NLA0: command.  > You can set up a symbol to clear the screen in your LOGIN.COM:   $ CLS :== TYPE/PAGE NLA0:   < ------------------------------------------------------------2 DCL4.   How do I do a REPLY/LOG in a batch stream?  F Your terminal must be enabled as an operator terminal before doing theD REPLY/LOG, but a batch stream doesn't have a terminal.  To make thisD work, use the following sequence to enable the OPA0: console as the 7 operator terminal; then the REPLY/LOG will be accepted:   "   $ DEFINE/USER SYS$COMMAND _OPA0:
   $ REPLY/LOG "   $ DEFINE/USER SYS$COMMAND _OPA0:   $ REPLY/ENABLE  H To disable the system console terminal (OPA0:) as an operator terminal,  use the following command:  "   $ DEFINE/USER SYS$COMMAND _OPA0:   $ REPLY/DISABLE   A Also see SYLOGICALS.COM (and SYLOGICALS.TEMPLATE) for information ? on configuring the behaviour of OPCOM, including the use of the C system console (OPA0:) as an operator and the specific contents and 7 behaviour of the system operator log file OPERATOR.LOG.  						[Arne Vajhj]  						[Stephen Hoffman]   < ------------------------------------------------------------1 DCL5.   How do I generate a random number in DCL?   B Here's my random number generator for inclusion into the OVMS FAQ;@ just do a GOSUB RAND and the global symbol RANDOM will contain aF randomly generated number.  The user/programmer can feed the generator0 a ceiling value (__CEIL) or a new seed (__SEED).  D $! RAND - returns a positive random number ("RANDOM") between 0 and  $!        __CEIL - 1.  $ RAND:  $  $ IF F$TYPE(__SEED) .EQS. "" $ THEN- $     ! seed the random number generator, ...  $     __NOW = F$CVTIME()& $     __HOUR = 'F$EXTRACT(11,2,__NOW)'( $     __MINUTE = 'F$EXTRACT(14,2,__NOW)'( $     __SECOND = 'F$EXTRACT(17,2,__NOW)'& $     __TICK = 'F$EXTRACT(20,2,__NOW)' $ A $     __SEED == __TICK + (100 * __SECOND) + (6000 * __MINUTE) + -           (360000 * __HOUR)D $     ! the generator tends to do better with a large, odd seed, ... $     __SEED == (__SEED .OR. 1)  $     ! clean up, ...  $     DELETEX/SYMBOL __NOW $     DELETEX/SYMBOL __HOUR  $     DELETEX/SYMBOL __MINUTE  $     DELETEX/SYMBOL __SECOND  $     DELETEX/SYMBOL __TICK  $ ENDIF  $ 5 $ IF F$TYPE(__CEIL) .EQS. "" THEN __CEIL = %X3FFFFFFF  $  $ __SEED == __SEED * 69069 + 1 $ 7 $ RANDOM == (__SEED.AND.%X3FFFFFFF)/(%X40000000/__CEIL)  $  $ RETURN$ 					[sharris@sdsdmvax.fb3.noaa.gov]  < ------------------------------------------------------------% DCL6.   What does the MCR command do?   D The MCR command runs the specified image, with a default filespec ofH SYS$SYSTEM:.EXE, and passes any (optional) command line arguments in the2 same manner as a foreign command.  In other words:   	$ MCR FOO BAR   is equivalent to:    	$ FOO :== $FOO 
 	$ FOO BAR  F It derives from the RSX operating system from which VMS evolved and isI still often used as a shortcut for activating images.  The MCR command is J different from the MCR command line interpreter, which is provided as partI of the optional VAX-11 RSX product that provides RSX emulation under VMS.   < ------------------------------------------------------------2 DCL7.   How do I change the OpenVMS system prompt?  M You can use the SET PROMPT command for this purpose.  SET PROMPT sets the DCL  prompt to the specified string.   K When you want to display variable information, you will need to establish a K tie-in that provides the information to the SET PROMPT command as required.   K If you wish to display the default directory for instance, you will have to L establish a tie between the SET DEFAULT command and the SET PROMPT commands,N as there is no direct way to get the default directory as the DCL prompt.  YouM can easily acquire or create a set of DCL command procedures that perform the M SET DEFAULT and SET PROMPT for you.  These DCL command procedures often use a  command such as:  !   $ set prompt='f$env("default")'   L More advanced users could implement a system service or other intercept, andF use these tools to intercept the directory change and reset the promptN accordingly.  (This approach likely involves some kernel-mode programming, andG requires write access to various undocumented OpenVMS data structures.)   E There are related tools available from various sources, including the  following web sites:  $   o ftp://ftp.hhs.dk/pub/vms/setpmt/  -   o ftp://ftp.tmesis.com/sys_service_hook.src   A   o James F. Duff has also made available a Macro32 tool known as H     TIME_PROMPT, a tool that sets the prompt to the current system time.  D   o Many folks have contributed DCL procedures to perform this task.>     Visit the newsgroup archives for information and examples.  H Information in this section has been acquired from various postings thatG have discussed this topic in the comp.os.vms newsgroup in the past, and I examples from Arne Vajhoej, Brian Schenkenberger, James Duff, and others.    				[Stephen Hoffman]   < ------------------------------------------------------------< DCL8.   Can I do DECnet task-to-task communication with DCL?   Yes, you can do this with DCL.  H The OpenVMS DECnet documentation shows various simple examples using theJ task object and the TYPE command to trigger the execution of a DCL commandJ procedure on a remote node.  A slightly more advanced example of using DCLJ for DECnet task-to-task -- a procedure that acts as both the client and asD the server as appropriate, and that uses a basic form of half-duplex communications -- is included:           $! x.com	         $ @         $! This procedure must be in the user's login directory.B         $! Requires a self-referential (not reverential :-) proxy:L         $!    UAF> add/prox <LocalNode>::<CurrentUser> <CurrentUser>/default?         $! Author: Stephen Hoffman, OpenVMS Engineering, Compaq 	         $          $ goto 'f$mode()'          $INTERACTIVE: *         $ open/read/write chan 0::"task=x"         $ write chan "Hello"         $ read chan parameter          $ close chan$         $ write sys$output parameter         $ exit         $BATCH:          $OTHER:          $NETWORK: &         $ open/read/write chan sys$net         $ read chan parameter -         $ write chan "''parameter' yourself!"          $ close chan         $ exit  -   An example of a run of the above procedure:            $ @x         Hello yourself! 	         $     L DCL does not include support asynchronous I/O, thus a predetermined protocolH or a predetermined "turn-around" command sequence must be implemented inI order to avoid protocol deadlocks -- cases where both tasks are trying to J write or both tasks are trying to read.  The task that is writing messagesI to the network must write (or write and read) a predetermined sequence of J messages, or it must write a message that tells the reader that it can nowL start writing messages.  (This is the essence of a basic half-duplex network protocol scheme.)  					[Stephen Hoffman]  < ------------------------------------------------------------" FILE1.  How can I undelete a file?  G OpenVMS doesn't have an "undelete" function.  However, if you are quick H to write-protect the disk (or if you can guarantee that no new files getC created or existing files extended), your data is still on the disk G and it may be possible to retrieve it.  The FLORIAN tool available from E the WKU Fileserver claims to be able to do this (see question SOFT1.) F Other alternatives here include the DFU tool, available on the OpenVMS Freeware CD-ROM distribution.   G If you are setting up a user environment for yourself or for others, it I is quite easy to use DCL to intercept the DELETE command, using a symbol:   '   $ DEL*ETE :== @SYS$LOGIN:MYDELETE.COM   J The DELETE symbol will cause the procedure to be invoked whenever the userF enters the DELETE command, and it can copy the file(s) to a "trashcan"K subdirectory before issuing a "real" DELETE on the files.  Other procedures G can retrieve the file(s) from the "trashcan" subdirectory, and can (and K should) clean out the "trashcan" as appropriate.  (Realize that this DELETE H symbol can interfere with DELETE/GLOBAL and other similar DCL commands.) 					[Stephen Hoffman]  < ------------------------------------------------------------B FILE2.  Why does SHOW QUOTA give a different answer than DIR/SIZE?  E DIR/SIZE doesn't take into account the size of file headers which are J charged to your quota.  Also, unless you use DIR/SIZE:ALL, you'll see onlyF the "used" size of the file, not the allocated size which is what getsK charged against your quota.  Also, you may have files in other directories.  					[Steve Lionel]   ! $ DIR/SIZ=ALL/GRAND [username...]   6 Grand total of D1 directories, F1 files, B1/B2 blocks.  # $ DIR/SIZ=ALL/GRAND [-]username.DIR   1 Grand total of 1 directory, 1 file, B3/B4 blocks.    $ SHOW QUOTA3   User [username] has B5 blocks used, B6 available, ?   of B7 authorized and permitted overdraft of B8 blocks on disk   F 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   M If the diskquota is out of synch, then the system-manager can make a rebuild.  					[Arne Vajhj]  G Also be aware that the DIRECTORY/SIZE command can report larger values  D than might otherwise be expected when used to evaluate files and/or H directories that are alias links -- such as the system roots on OpenVMS G system disks -- as the command reports a total that is cumulative over  I all of the files and directories examined, without regard for which ones  M might be alias entries and which are not.  (In other words, a DIRECTORY/SIZE  M of an entire OpenVMS system disk will report a disk useage value larger than  L the (usually more accurate) value reported by the SHOW DEVICE command.  ThisP as a result of the alias entries linking each SYS$SYSDEVICE:[SYSCOMMON]SYS*.DIR K directory file and the SYS$SYSDEVICE:[000000]VMS$COMMON.DIR file together.)   < ------------------------------------------------------------B FILE3.  How do I make sure that my data is safely written to disk?  E If your application must absolutely guarantee that data is available, K no matter what, there's really no substitute for RMS Journalling.  However, J you can achieve a good degree of data integrity by issuing a SYS$FLUSH RMSD call at appropriate times (if you're using RMS, that is.)  If you'reM using a high-level language's I/O system, check that language's documentation F to see if you can access the RMS control blocks for the open file.  InC C you can use fflush followed by fsync.  Note that fsync, which was K undocumented for VAX C but is documented for DEC C, takes a file descriptor  as an argument, not a *FILE.  < ------------------------------------------------------------C FILE4.  What are the limits on file specifications and directories?   G A file specification has an aggregate maximum size of 255 characters at N present.  The node and device specification may be up to 255 characters each -L file name and file types may be up to 39 characters each.  File versions areK from 1 through 32767, though 0 (latest version), -0 (oldest version) and -n K (n'th previous version) can be used in most contexts.  A file specification N may not have more than 8 directories and subdirectories - while it is possibleK to create subdirectories of greater depth, accessing them is problematic in ' most cases and this should be avoided.    G Application developers should use OpenVMS-supplied routines for parsing I file specifications - this ensures that changes in what is allowable will G not tend to break your application.  Consider that various parts of the F file specification may contain quoted strings with embedded spaces andI other punctuation!  Some routines of interest are SYS$FILESCAN, SYS$PARSE I and LIB$TRIM_FILESPEC.  For further information, see the OpenVMS Guide to  File Applications.  < ------------------------------------------------------------@ FILE5.  What is the largest disk volume size OpenVMS can access?  M One Terabyte (2**31 blocks of 2**9 bytes).  Prior to the release of V6.0, the K OpenVMS file system was limited to disk volumes of 8.5 GB (2**24 blocks) or  less.   M On some systems, there are restrictions in the console program that limit the J size of the OpenVMS system disk.  Note that data disks are not affected byH console program limits.  For example, all members of the VAXstation 3100K series are limited to a system disk to 1.073 GB or less due to the console, & though larger data disks are possible.  D Some SCSI disks with capacities larger than 8.6 gigabytes (GB) will G require the use of an OpenVMS ECO kit (eg: ALPSCSI04_062 or later) for  F new SCSI device drivers.  Failure to use this ECO can cause "rounding E errors" on the SCSI disk device capacity -- OpenVMS will not use nor  J display the full capacity of the drive -- and  "%sysinit-e-error mounting E system device status equals 000008C4" (8C4 -> "%SYSTEM-?-FILESTRUCT,  B unsupported file structure level") errors during bootstrap.  (One E workaround for the bootstrap when the bitmap is located far into the  D disk is the use of INIT/INDEX=BEGIN.)  The problem here involves theG particular extensions and fields used for larger capacity disks within  F the SCSI specifications and within the various intepretations of same. 					[Stephen Hoffman]   For IDE disk drives:  >   o Versions of DQDRIVER *BEFORE* X-15 topped out at 8.455 GB.-     Fixed drivers (>="X-15") were shipped in:   %       OpenVMS Alpha V7.2-1, and later %       V7.2 UPDATE V1.0 ECO, and later '       V7.1-2 UPDATE V1.0 ECO, and later '       V7.1-2 UPDATE V3.0 ECO, and later   <   o The newer DQDRIVER driver operates to disks up to 33 GB ?     without (known) problems, and effectively works with rather A     larger disks (up to circa 137 GB?) but is known to report an  ;     incorrect number of "cylinders" with disks above 33 GB.   C Be aware that a known restriction in certain older versions of the  ? Alpha SRM Console prevents booting most IDE drives larger than  C 8.455 GB, depending on exactly where the various files are located  B on the volume.  Updated SRM consoles for systems with SRM and IDE A drive support are (will be) available.  (OpenVMS Engineering has  ? successfully bootstrapped 20GB IDE disks using the appropriate   SRM console version.)   F NOTE: All IDE-related disk sizes listed in this section are stated in G units of "disk (base 10) gigabytes" (1GB = 10^9 bytes) and NOT in units A of "software (base 2) gigabytes" (1GB = 2^30 (1073741824.) bytes. 8                                         [Atlant Schmidt]    < ------------------------------------------------------------E FILE6.  What is the maximum file size, and the RMS record size limit?   D RMS can store individual files of a size up to the maximum supportedG volume size.  Under OpenVMS V6.0 and later, the volume size and the RMS D maximum file size limit is 2**31 * 512 bytes -- one terabyte (1 TB).  F The RMS formats -- sequential, relative, and indexed -- are limited byE the one terabyte maximum volume size.  RMS relative files are further D limited to a number of records that will fit in 32 bits -- 4 billionE records.   Sequential and indexed formats do not have a record limit.    Also see PROG14. 					[Stephen Hoffman]  < ------------------------------------------------------------= FILE7.  How do I write recordable CD media (CD-R) on OpenVMS?   B Creation of CD-ROMs using recordable CD media (CD-R) under OpenVMSA typically involves one of two approaches: the use of the optional B CD-R (`Scribe') capabilities available for the InfoServer or otherD "offline" hardware packages, or the use of a host-based package such> as the CDWRITE13_VMS utility, an OpenVMS port of a Linux tool.  ; OpenVMS has no integrated support for recording CD-R media.   6 OpenVMS can read both ODS2 and ISO9960 format CD-ROMs.  F InfoServer hardware configurations are no longer availble from Compaq,4 but may potentially be acquired through other means.  E The CDWRITE13_VMS package is one example of a host-based package that C can be used to create CD-R media.  The contact for CDWRITE13_VMS is E Dr. Eberhard Heuser-Hofmann.  One website that discusses this package  is located at:  A   http://www.geocities.com/SiliconValley/Lakes/9999/vmscdwri.html   4 Also see the newest linux-cdwrite package, XCDROAST.  = Additional information is available via David J. Dachtera at:   2   http://home.earthlink.net/~djesys/vms/cdrom.html  	 Also see:   6   http://www.cd-info.com/CDIC/Technology/CD-R/vms.html  B   http://www.faqs.org/faqs/cdrom/cd-recordable/part1/preamble.html     ;                                           [Stephen Hoffman]   < ------------------------------------------------------------7 FILE8.  What I/O transfer size limits exist in OpenVMS?   G The maximum transfer size is an attribute of the particular I/O device, E controller and driver combination; there is no inherent limit imposed E by OpenVMS (other than the fact that, today, byte counts and LBNs are  generally limited to 32 bits).  C The maximum size of a device I/O request is limited by the value in A UCB$L_MAXBCNT, which is set by the device driver based on various D factors.  (Also check the setting of the MAXBUF system parameter for6 buffered I/O transfers, and check the process quotas.)  D Currently, SCSI drivers limit I/O transfers to FE00(16) bytes, 65024K bytes (decimal).  The reasons for this transfer size limitation are largely C historical.  Similarly, DSSI devices are limited to the same value, D this for hardware-specific reasons.  Transfers to HSC and HSJ deviceJ controllers via the CI are limited to 1,048,576 bytes.  Client MSCP-servedA devices are limited to 65535 bytes -- to help ensure that the I/O D fragmentation processing happens on the client and not on the server system.   H Parts of the OpenVMS I/O subsystem are optimized for data transfers lessF than 64KB, because (obviously) most I/O operations are (substantially)G less than that.  OpenVMS can handle larger transfers, if the driver and  the device can handle it.    Also see FILE4, FILE5   4                                         [John Croll]  < ------------------------------------------------------------: PROG1.  How do I call <routine_name> from <language_name>?  F Most OpenVMS system services and RTL routines pass string arguments byD descriptor.  Languages which support native string data types createK descriptors automatically; those which do not (eg., C) require that you set  them up explicitly.  					[eric@tardis.HQ.ileaf.com]   F There is a lot of information available on how to call system servicesH and Run-Time Library routines, including examples in numerous languages. The best references are:   	Your language's User Manual' 	OpenVMS Programming Environment Manual $ 	OpenVMS Programming Concepts Manual9 	OpenVMS Programming Interfaces: Calling a System Routine  	OpenVMS Calling Standard   G In addition, if you are a subscriber to the Compaq Software Information J Network (available to those with a software support contract), the supportH database contains hundreds of worked examples of calling system servicesJ and RTL routines, including the one that seems to trip up almost everyone, SMG$CREATE_MENU. 					[Steve Lionel]   F Arne Vajhj has put together a collection of OpenVMS example programs. It can be found at:    ftp://ftp.hhs.dk/pub/vms/  					[Arne Vajhj]  B Additional information and examples for OpenVMS are available via:  (   http://www.openvms.digital.com/wizard/*   http://www.openvms.digital.com/freeware/   					[Stephen Hoffman]  < ------------------------------------------------------------9 PROG2.  How do I get the arguments from the command line?   G If you're writing a program and want to accept arguments from a foreign F command, you can use LIB$GET_FOREIGN to get the command line and parseD it yourself, or if you're programming in C, use the normal argc/argv method.   J To write an application which uses the normal DCL verb/qualifier/parameterF syntax for invocation, see the description of the CLI$ routines in the3 OpenVMS Callable Utility Routines Reference Manual.   I It is possible to write an application which can be used both ways; if a  L DCL verb isn't used to invoke the image, the application parses the command H 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 question DCL1.   < ------------------------------------------------------------= PROG3.  How do I get a formatted error message in a variable?   D Use the SYS$PUTMSG system service with an action routine that storesG the message line(s) in the variable of your choice.  Be sure the action K routine returns a "false" (low bit clear) function value so that SYS$PUTMSG I doesn't then try to display the message (unless you want it to.)  See the E description of $PUTMSG in the System Services Reference Manual for an # example of using an action routine.   < ------------------------------------------------------------D PROG4.  How do I link against SYS$SYSTEM:SYS.STB on an Alpha system?  G LINK/SYSEXE is the OpenVMS Alpha equivalent of linking against SYS.STB.   < ------------------------------------------------------------8 PROG5.  How do I do a SET DEFAULT from inside a program?  H The problem is that SYS$SETDDIR only changes the default directory - NOTI the default disk. The default disk is determined by the logical SYS$DISK. B If you want to change the default disk within a program, then callJ LIB$SET_LOGICAL to change the logical SYS$DISK. You will need to call bothK LIB$SET_LOGICAL and SYS$SETDDIR to change both default disk and the default 
 directory! 					[Arne Vajhj]	   < ------------------------------------------------------------M PROG6.  How do I create a shareable image transfer vector on an Alpha system?   K This is something that was greatly simplified for OpenVMS Alpha.  You don't L need to create a separate transfer vector module; just use the SYMBOL_VECTORI statement in a linker options file.  For example, if your shareable image J has two routines named FOO and BAR, the linker options file should contain the following line:   - 	SYMBOL_VECTOR=(FOO=PROCEDURE, BAR=PROCEDURE)   + The Linker manual has more details on this.   < ------------------------------------------------------------H PROG7.  How do I turn my Fortran COMMON into a shareable image on Alpha?  M You need to add SYMBOL_VECTOR=(<common-name>=PSECT) to your options file.  On G OpenVMS VAX all OVR/REL/GBL psects were automatically exported into the M shareable image's Global Symbol Table.  On OpenVMS Alpha you have to tell the C linker that you want this done by means of the PSECT keyword in the % SYMBOL_VECTOR options file statement.   N This has several advantages over OpenVMS VAX.  First, you don't have to worry F about the address of the psect when you try to create a new, upwardly H compatible version of the shareable image. Second, you can control which= psects, if any, are made visible outside the shareable image.   K By default, COMMON PSECTs in DEC Fortran for OpenVMS Alpha (as well as most L other OpenVMS Alpha compilers) are NOSHR.  On VAX, the default was SHR whichG required you to change the attribute to NOSHR if you wanted your COMMON G 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=SHRM in the Fortran source code (the CDEC$ must be begin in column 1) or a linker  K options file PSECT_ATTR statement to set the COMMON PSECT attribute to SHR.   / For further information, see the Linker manual.   < ------------------------------------------------------------< PROG8.  How do I convert between IEEE and VAX floating data?  G In OpenVMS V6.1 there is a routine CVT$CONVERT_FLOAT, documented in the E LIB$ Run-Time Library Reference Manual, which can perform conversions C between any two of the following floating datatypes: VAX (F,D,G,H), K little-endian IEEE (single, double, quad), big-endian IEEE (single, double,  quad), CRAY and IBM System\370.   F DEC Fortran (all platforms) has a feature which will perform automaticK conversion of unformatted data during input or output.  See the DEC Fortran A documentation for information on "non-native data in I/O" and the   CONVERT= OPEN statement keyword.  4 For further floating-point related information, see:  .   ftp://ftp.hhs.dk/pub/vms/collection/ieee.zip  < ------------------------------------------------------------= PROG9.  How do I get the argument count in a Fortran routine?   E On VAX, many programmers would use a MACRO routine which accessed the E AP register of the caller to get the address of the argument list and F hence the argument count.  This was not guaranteed to work on VAX, butH usually did.  However, it doesn't work at all on OpenVMS Alpha, as thereH is no AP register.  On Alpha systems, you must use a language's built-inD function to retrieve the argument count, if any.  In Fortran this isA IARGCOUNT, which is also available in DEC Fortran on OpenVMS VAX.   G Note that omitting arguments to Fortran routines is non-standard and is G unsupported.  It will work in many cases - read the DEC Fortran release ! notes for additional information.   < ------------------------------------------------------------? PROG10. How do I get a unique system ID for licensing purposes?   G Many software developers desire to use a unique hardware ID to "lock" a F given copy of their product to a specific system.  Most VAX and Alpha G systems do not have a unique hardware-set "system ID" that can be used  D for this purpose.  Compaq does not use hardware IDs in its licensingG methods and many users consider a hardware-based licensing scheme to be 9 a negative attribute when considering software purchases.   J Compaq OpenVMS uses a software-based system called the License Management H Facility (LMF).  This provides for software keys (Product Authorization G Keys or PAKS) which support capacity and user-based license checking.   @ Compaq offers an LMF PAK Generator to CSA members -- see ALPHA4.  J However, if a hardware-based method is required, the most common method isF based on an Ethernet adaptor hardware address.  Sample source code for" implementing this is available at:  (   http://www.openvms.digital.com/wizard/  < ------------------------------------------------------------? PROG11. What is an executable, shareable, system or UWSS image?   A    Executable code in OpenVMS typically resides in an image -- an B    image is a file -- the file extension is typically .EXE -- thatA    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.A       These images can grant enhanced privileges, with an INSTALL @       of the image with /PRIVILEGE, or can grant enhanced accessA       with the specification of a subsystem identifier on the ACL         associated with the image.  B    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 beA        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'.)  A    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.    F    Protected images -- also refered to as User-Written System ServicesC        (UWSS), or as privileged shareable images -- are similiar in A        some ways to a standard shareable images, but these images A        include a `change mode' handler, and execute in an `inner' A        processor mode (privileged mode; executive or kernel), and C        code executing in inner modes has implicit SETPRV privilege. B        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 6        located in other protected or shareable images.  A    Loadable images and device drivers are images that can be used >    to add code into the OpenVMS kernel.  Pseudo-device driversA    are a particularly convenient way to add executable code, with >    associated driver-defined data structures, into the kernel.E    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 is1    available at the (admittedly overly long) URL:   +      http://www.openvms.digital.com/wizard/    					[Stephen Hoffman]  < ------------------------------------------------------------/ PROG12. How do I do a file copy from a program?   M There are several options available for copying files from within a program.  D Obvious choices include using lib$spawn(), system(), sys$sndjbc() orM sys$creprc() to invoke a DCL COPY command.  Other common alternatives include J using the callable convert routines and the BACKUP application programming interface (V7.1 and later).    					[Stephen Hoffman]  < ------------------------------------------------------------ PROG13.  What is a descriptor?  K A descriptor is a data structure that describes a string or an array.  Each I descriptor contains information that describes the type of the data being G referenced, the size of the data, and the address of the data.  It also I includes a description of the storage used for the data, typically static 2 or dynamic.   Descriptors are passed by reference.  B The following are examples of creating and using descriptors in C:       #include <descrip.h>     #include <lib$routines.h>      #include <stsdef.h>      int RetStat;     char TxtBuf[TXTSIZ] %     struct dsc$descriptor StaticDsc = 0       { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL };#     struct dsc$descriptor DynDsc =  0       { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };     int DynDscLen = 255;0     $DESCRIPTOR( ConstDsc, "This is a string" );  /     /* finish setting up a static descriptor */ )     StaticDsc.dsc$w_length      = TXTSIZ; 2     StaticDsc.dsc$a_pointer     = (void *) TxtBuf;  0     /* finish setting up a dynamic descriptor */2     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;   G Static descriptors reference storage entirely under application program J control, and the contents of the descriptor data structure can be modifiedE as required (by the application).  OpenVMS routines do not modify the H contents of a static descriptor, nor do they alter the address or lengthI values stored in the static descriptor.  (The term "static" refers to the H descriptor data structure, and not necessarily to the storage referenced by the descriptor.)   G Dynamic descriptors reference storage under the control of the run-time H library, and the contents of a dynamic descriptor data structure -- onceE initialized -- can only be modified under control of run-time library F routines.  The dynamic storage referenced by the dynamic descriptor isC allocated and maintained by the run-time library routines.  Various H OpenVMS routines do alter the contents of the descriptor data structure,K changing the value for the amount and the address of the storage associated H with the dynamic descriptor, as required.  Routines can obviously accessC and alter the contents of the storage referenced by the descriptor.   I OpenVMS languages that include support for strings or arrays are expected I to use descriptors for the particular structure.  Most OpenVMS languages, J such as Fortran and BASIC, use descriptors entirely transparently.  Some, H like DEC C, require the programmer to explicitly create and maintain the descriptor.   K For further information on string descriptors, see the _OpenVMS Programming 8 Concepts_ manual, part of the OpenVMS documentation set.   					[Stephen Hoffman]  < ------------------------------------------------------------, PROG14.  How many bytes are in a disk block?  G A disk block is the minimum unit of disk storage allocation in OpenVMS.   B Under OpenVMS VAX and OpenVMS Alpha, the disk volume block size is1 consistent, with each block containing 512 bytes.   D The minimum disk allocation granularity actually permissible (in theI ODS-2 and ODS-5 volume structures commonly used on OpenVMS) is determined E on a per-volume basis, and is typically based on a combination of the G total number blocks on the disk volume and the total size of the volume J storage bitmap.  The allocation granularity is known as the volume clusterG factor -- the cluster factor is the number of blocks in a disk cluster, B and it is the smallest number of blocks that can be allocated on a particular disk volume.   B Prior to OpenVMS V7.2, the  maximum permissible size of the bitmapC requires larger cluster factors as volume sizes increase.  Starting D with V7.2, the bitmap can be larger, and cluster factors as small as one block can be used.  B The number of bytes in a file can be determined by multiplying theD number of blocks allocated for the file times the number of bytes inA a block.  For sequential files (only), the FFB (XAB$W_FFB, in the C File Header XAB) value can be used to find out how much of the last ? (XAB$L_EBK) block is used.  FFB and EBK are meaningful only for @ sequential files, and only in a limited context -- partial blockF allocations are not permitted.  For other file formats, the EOF marker is not meaningful.  C Disk allocations always occur only in units of the cluster factors, D which can be from one block up to (potentially) clusters of eighteen7 blocks or more, depending on the volume cluster factor.   H OpenVMS assumes that the device driver and the underlying storage deviceE will present the file system with addressable units of storage of 512 E bytes in size, or the appearance of same.  Various third-party CD-ROM F devices, for instance, support only 2048 byte blocks, and such devices: are incompatible with the standard OpenVMS device drivers.  B To determine the number of bytes required for a file from DCL, oneB option uses the f$file_attributes item EOF, multiplied by the size@ of a block in bytes (512).  This does not account for the unusedB space in the last block of a sequential file, but it also does not8 have to differentiate sequential files from other files.   					[Stephen Hoffman]  < ------------------------------------------------------------, PROG15. How many bytes are in a memory page?  B A memory page is the minimum unit of memory allocation in OpenVMS.C With OpenVMS VAX, the memory page size matches the disk block size:  it is always 512 bytes.   F With OpenVMS Alpha, the memory page size is variable, and it can rangeE from 8192 bytes (8 kilobytes) up to 64 kilobytes.  The current system F page size can be determined using the sys$getsyi or f$getsyi PAGE_SIZEE item.  Programs with hardcoded constants for the memory page size (or A page alignment) should always assume a page size of 64 kilobytes.   D On OpenVMS Alpha, a 512 byte area of memory -- equivilent in size to9 an OpenVMS VAX memory page -- is refered to as a pagelet.    					[Stephen Hoffman]  < ------------------------------------------------------------9 PROG16. How do I create a process under another username?   G Many server processes can operate within the context of the target user F using privileges, using calls such as sys$chkpro and (more commonly inH this context) sys$check_access as needed to determine if access would beC permitted for the specified user within the current security model.   H With OpenVMS V6.2 and later, the persona system services (SYS$PERSONA_*)J can be used to assume the persona of the specified user -- these allow theF server to operate as the specified user, in a controlled fashion.  TheG persona services can be used as a "wrapper" around a sys$creprc process F creation call, as well -- this will create a seperate process entirely under the assumed persona.  E Information on the persona system services is included in the OpenVMS I V6.2 new features documentation, and in the OpenVMS V7.1 and later system I services documentation.  These system services exist and are supported in   OpenVMS V6.2 and later releases.  I 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 of5       username and password, or using a DECnet proxy. <       This creates a network-mode job under the target user.A       The network-mode job might do little more than a RUN/DETACH <       of an image passed in via task-to-task -- task-to-taskB       communications are fully available using strictly DCL-to-DCL=       processing, or using a compiled language and DCL, etc.) C     o SUBMIT/USER, or the username argument on the sys$sndjbc call. A       This creates a batch-mode job under the specified username. ?       The batch-mode job might do little more than a RUN/DETACH ,       of an image passed in via a parameter..     o the UIC argument on the sys$creprc call.B       This mimics the UIC of the target user, and is certainly not+       the prefered mechanism for this task.      o Via pseudo-terminals...   J There are likely a few other mechanisms around...  There are various toolsG available from DECUS and other sources that allow various forms of user J impersonation, as well.  These tools will require version-dependent kernelF code and enhanced privileges for some of (or all of) their operations.   					[Stephen Hoffman]  < ------------------------------------------------------------E PROG17.  Why do lib$spawn, lib$set_symbol fail in detached processes?   F The processing within run-time library (RTL) calls such as lib$attach,B lib$disable_ctrl, lib$do_command, lib$enable_ctrl, lib$get_symbol,C lib$run_program, lib$set_symbol, lib$set_logical, and lib$spawn, is H dependent on and requires the presence of a command language interpreterH (CLI), such as DCL.  Without a CLI present in the current process, theseI calls will fail with a "NOCLI, no CLI present to perform function" error.   7 Detached processes typically do not have a CLI present.   H In place of lib$spawn, sys$creprc can often be used.  The context of theF parent process (symbols and logical names) will not be propogated intoC the subprocess when sys$creprc is used, though when there is no CLI : present in the process this (lack of) propogation is moot.  I To create a detached process with a CLI, you must specify LOGINOUT as the G target image as discussed elsewhere in the FAQ, or only use these calls H (and any other calls requiring a CLI) from images that are running in an0 "interactive", "batch", or "other" mode process.   					[Stephen Hoffman]  < ------------------------------------------------------------J PROG18.  Where can I obtain Bliss, and the libraries and supporting files?  < The Bliss language compilers and documentation are available& on the OpenVMS Freeware distributions.  A Bliss language source code that contains the following statement:   $   LIBRARY 'SYS$LIBRARY:STARLET.L32';  ? or similar requires the presence of the Bliss libraries.  These B libraries are created on the target system using the Bliss require8 files, and are built using the following Bliss commands:  8   STARLET.L32 contains the public interfaces to OpenVMS:  5     $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L32 -          SYS$LIBRARY:STARLET.REQ   E   LIB.L32 contains both the public and private interfaces to OpenVMS:   1     $ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]LIB.L32 - 3         SYS$LIBRARY:LIB.REQ+SYS$LIBRARY:STARLET.REQ   4   The equivilent files for Bliss64 are created with:  5     $ BLISS/A64/LIBRARY==SYS$COMMON:[SYSLIB]LIB.L64 - 3         SYS$LIBRARY:LIB.R64+STARLET.REQ+STARLET.R64 9     $ BLISS/A64/LIBRARY==SYS$COMMON:[SYSLIB]STARLET.L64 -          SYS$LIBRARY:STARLET.R64   D Some Bliss code may also require the OpenVMS VAX architecture flags.B The following is the equivilent of the Alpha ARCH_DEFS.BLI module:     ! 9   ! This is the OpenVMS VAX version of ARCH_DEFS.BLI, and <   ! contains the architectural definitions for conditionally;   ! compiling OpenVMS Bliss sources for use on VAX systems.    !    MACRO VAXPAGE = 1%;    MACRO BIGPAGE = 0%;   =   MACRO VAX =                     ! = 1 if compiled BLISS/VAX A           %BLISS(BLISS32V)%;      ! = 0 if not compiled BLISS/VAX   <   MACRO EVAX =                    ! = 1 if compiled BLISS/E*   ! @   ! A more appropriate definition can only be used with versions=   ! of the Bliss compilers that understand the 32E/64E flags. G   !       %BLISS(BLISS32E) OR %BLISS(BLISS64E)%; ! = 0 if compiled /VAX 8           NOT %BLISS(BLISS32V)%;  ! = 0 if compiled /VAX     MACRO ADDRESSBITS = E           %BPADDR%;               ! = 32 or 64 based on compiler used        					[Stephen Hoffman]  < ------------------------------------------------------------0 PROG19. How can I open a file for shared access?  9   When creating a file, it is often useful to allow other 8   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.   8   A C source example that demonstrates how to do this is7   available in topic 2867 in the OpenVMS Ask The Wizard    area:   *     http://www.openvms.digital.com/wizard/  ;   Depending on the environment, you may need to use C calls ;   such as fsync and fflush, and -- in specific cases -- the    setvbuf(_IONBF) call.    					[Stephen Hoffman]   [End of Part 3/4]   N  --------------------------- pure personal opinion ---------------------------L    Hoff (Stephen) Hoffman   OpenVMS Engineering   hoffman#xdelta.zko.dec.com