                                 DCL Details        G                    operation, but these process-local logical names are G                    neither copied back into the parent process when the E                    subprocess exits, nor are these logical names ever                     shared.  H                    Logical names are implemented deep within the OpenVMSI                    executive, and are organized into logical name tables. E                    Logical names can be stored in tables private to a G                    process( LNM$PROCESS, the process-local logical nameuJ                    table) , that can be shared among processes in the sameH                    job tree ( LNM$JOB, the job logical name table) or inJ                    logical name tables that are shared among larger groupsE                    of processes (eg: LNM$GROUP, the UIC group logical J                    name table and LNM$SYSTEM, the system-wide logical nameJ                    table). Logical names are centrally intended to provideE                    various I/O-related capabilities, including device J                    independence and configuration customization-correctly-H                    written application programs can use logical names toJ                    avoid embedding specific device or device and directoryJ                    specifications, and to allow filename and configuration"                    customizations.  I                    One of the most powerful capabilities of logical namesrG                    beyond the device independence provided involves thetC                    defaulting capabilities; you can use RMS parsingtD                    (directly, or with mechanisms such as the f$parseH                    lexical function) to provide a filename and a defaultH                    filename. To provide the mechanism that allows SYSUAFD                    to be located in an arbitrary position or even anA                    arbitrary filename, a construct similar to theo%                    following is used:   >                    $ UAF = F$PARSE("SYSUAF","SYS$SYSTEM:.DAT")  C                    This design allows the logical name SYSUAF to be(H                    optionally defined, and - when present-to specify theE                    particular location and name of the file. PortionslF                    of the full file specification that are omitted areI                    retrieved using the default translation of SYS$SYSTEM:a-                    and the file type of .DAT.   G                    Logical names also have assigned processor modes, asUH                    some translations must be trustworthy. In the exampleI                    above, only trusted and privileged system users shouldsI                    be able to redirect the SYSUAF authorization database,f                      8-2                                   DCL Details        G                    so any definition of the SYSUAF logical name must beTJ                    made in EXECUTIVE mode in a trusted logical name table.  G                    As for common OpenVMS terminology, logical names aremH                    "defined" and the associated processing is refered toH                    as "translation", while symbols are "equated" and theI                    associated processing is refered to as "substitution". D                    "Lexical functions" are processing routines builtH                    into DCL, and typically prefixed with f$. Many of theI                    lexical functions are built upon correspondingly-named 3                    system services, though not all.i  G                    Symbol substitution occurs only when the DCL commandiD                    interpreter is reading and processing the commandI                    input; for information on DCL symbol substitution, see I                    Section 8.10. For program access, see the RTL routinest6                    lib$set_symbol and lib$get_symbol.)  J                    For information on logical name translation, please seeH                    f$trnlnm lexical function and the DCL commands DEFINEF                    and DEASSIGN, as well as underlying system servicesF                    such as sys$trnlnm. Logical name translation occursE                    when requested, or as the file or I/O operation isi                    started.   E                    Please see the OpenVMS User's Guide in the OpenVMS H                    documentation set for a far more detailed description'                    of these constructs.s  E                    For related materials, please see Section 8.10 andI                     Section 8.11.  D           __________________________________________________________5           8.2  How do I run a program with arguments?   E                    The RUN command does not accept arguments. To pass F                    arguments to a program, you must use what is calledF                    a "foreign command", and either an explicit commandF                    as shown here, or an automatic foreign command. For                    example:s  3                    $ unzip :== $disk:[dir]unzip.exei                    $ unzip -?_  J                                                                        8-3 r  a                              DCL Details        G                    The leading $ in the equivilence name for the symboltD                    definition is what makes the DCL symbol a foreignD                    command. If the device and directory are omitted,*                    SYS$SYSTEM: is assumed.  G                    Under OpenVMS V6.2 and later, DCL supports automatic]B                    foreign command definition via the logical nameG                    DCL$PATH. An example of a definition of this logical                     name is:   M                    $ DEFINE DCL$PATH SYS$DISK:[],ddcu:[mytooldir],SYS$SYSTEM:   G                    DCL will first look for a command in the DCL command E                    table, and if no match is found and if DCL$PATH is H                    defined, it will then look for command procedures andH                    executable images with filenames matching the commandH                    specified, in the directories specified via DCL$PATH.G                    The first match found is invoked, and under OpenVMS, I                    the DCL$PATH support will cause a command procedure to E                    be activated in preference to an executable image.   A                    For more information on foreign commands or on E                    automatic foreign command support, see the OpenVMSd!                    User's Manual.g  )                    See also Section 10.3.   F                    If you want to create a detached process that takesJ                    arguments from a command line, it must be run under theI                    control of a command line interpreter (CLI) (typically F                    DCL). This is done by placing the command line in aH                    file, specifying SYS$SYSTEM:LOGINOUT.EXE as the imageI                    to run and the command file as the input. For example:   2                    $ OPEN/WRITE CMD TEMP_INPUT.COM6                    $ WRITE CMD "$ MYCOMMAND arguments"                    $ CLOSE CMDK                    $ RUN/DETACHED SYS$SYSTEM:LOGINOUT /INPUT=TEMP_INPUT.COM   F                    Various OpenVMS library calls (such as lib$spawn(),E                    cli$dcl_parse(),  and the C library system() call) G                    require access to a command line interpreter such as I                    DCL to perform requested actions, and will not operate -                    if a CLI is not available.C                      8-4 E  D                              DCL Details        E                    When a CLI is not available, these calls typicallyMF                    return the error status SS$_NOCLI. And as mentionedH                    above, invoke the image LOGINOUT to cause a CLI (suchF                    as DCL) to be mapped into and made available in the1                    context of the target process.e  J                    For examples of how TCP/IP Services sets up its foreignB                    commands (which includes tools such as uuencodeF                    and uudecode), please see the DCL command procedure9                    SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM.o  )                    Also see Section 8.12.   D           __________________________________________________________1           8.3  How can I clear the screen in DCL?i  C                    The simplest way is the TYPE/PAGE NLA0: command.   F                    You can set up a symbol to clear the screen in your                    LOGIN.COM:h  ,                    $ CLS :== TYPE/PAGE NLA0:  D           __________________________________________________________B           8.4  Using REPLY/LOG from DCL? Disabling Console OPCOMs?  H                    Your terminal must be enabled as an operator terminalF                    before the REPLY/LOG command can be used, but a DCLF                    procedure (batch command file, system startup, etc)E                    does not have an associated terminal. To make thisrG                    work, use the following sequence to enable the OPA0:EG                    console as the operator terminal, then the REPLY/LOG_,                    command will be accepted:  3                    $ DEFINE/USER SYS$COMMAND _OPA0:e                    $ REPLY/LOG3                    $ DEFINE/USER SYS$COMMAND _OPA0:O!                    $ REPLY/ENABLE   G                    To disable the system console terminal (OPA0:) as an @                    operator terminal, use the following command:  3                    $ DEFINE/USER SYS$COMMAND _OPA0:e"                    $ REPLY/DISABLE  J                                                                        8-5 d  l                              DCL Details        H                    Also see SYLOGICALS.COM (and SYLOGICALS.TEMPLATE) forE                    information on configuring the behaviour of OPCOM, D                    including the (default) use of the system consoleD                    (OPA0:) as an operator terminial and the specificI                    contents and behaviour of the system operator log file$                     OPERATOR.LOG.  D           __________________________________________________________8           8.5  How do I generate a random number in DCL?  @                    With V7.3-2 and later, f$unique can be usefulF                    here. Alternatively, here is a pseudo-random numberH                    generator, just do a GOSUB RAND and the global symbolG                    RANDOM will contain a randomly generated number. You H                    can feed the generator a ceiling value (__CEIL)  or a%                    new seed (__SEED)._  M           $! RAND - returns a positive random number ("RANDOM") between 0 ande           $!        __CEIL - 1. -           $! sharris-at-sdsdmvax.fb3.noaa.gove           $ RAND:            $ &           $ IF F$TYPE(__SEED) .EQS. ""           $ THEN7           $     ! seed the random number generator, ...o"           $     __NOW = F$CVTIME()0           $     __HOUR = 'F$EXTRACT(11,2,__NOW)'2           $     __MINUTE = 'F$EXTRACT(14,2,__NOW)'2           $     __SECOND = 'F$EXTRACT(17,2,__NOW)'0           $     __TICK = 'F$EXTRACT(20,2,__NOW)'           $rK           $     __SEED == __TICK + (100 * __SECOND) + (6000 * __MINUTE) + -a$                    (360000 * __HOUR)N           $     ! the generator tends to do better with a large, odd seed, ...)           $     __SEED == (__SEED .OR. 1)b           $     ! clean up, ... $           $     DELETEX/SYMBOL __NOW%           $     DELETEX/SYMBOL __HOUR '           $     DELETEX/SYMBOL __MINUTEW'           $     DELETEX/SYMBOL __SECOND(%           $     DELETEX/SYMBOL __TICK'           $ ENDIFW           $ ?           $ IF F$TYPE(__CEIL) .EQS. "" THEN __CEIL = %X3FFFFFFF                       8-6                                   DCL Details                   $ (           $ __SEED == __SEED * 69069 + 1           $EA           $ RANDOM == (__SEED.AND.%X3FFFFFFF)/(%X40000000/__CEIL)            $/           $ RETURN  D           __________________________________________________________,           8.6  What does the MCR command do?  H                    The MCR is an artifact of RSX compatibility mode, theH                    operating system from which OpenVMS is descended. MCRE                    is the Monitor Console Routine, and the command is I                    intended to activate RSX compatibility mode utilities. E                    When used on OpenVMS, the command is most commonly G                    used to run the specified image and-because the tool_G                    detects the image is not a compatibility-mode image- D                    it acts as a form of RUN command with the defaultH                    file specification of SYS$SYSTEM:.EXE. MCR passes anyI                    (optional) command line arguments in a fashion similar 8                    to a foreign command. In other words:                       $ MCR FOO BAR  $                    is equivalent to:  "                     $ FOO :== $FOO                     $ FOO BARc  I                    MCR is not documented. Use of a foreign command or theoH                    DCL$PATH mechanism is preferred. For details on this,#                    see Section 8.2.f  D           __________________________________________________________9           8.7  How do I change the OpenVMS system prompt?   G                    You can use the SET PROMPT command for this purpose.OJ                    SET PROMPT sets the DCL prompt to the specified string.  E                    When you want to display variable information, youoD                    will need to establish a tie-in that provides theE                    information to the SET PROMPT command as required.S  C                    If you wish to display the default directory for_E                    instance, you will have to establish a tie between J                    the SET DEFAULT command and the SET PROMPT commands, asI                    there is no direct way to get the default directory as.  J                                                                        8-7                                   DCL Details        I                    the DCL prompt. You can easily acquire or create a setrI                    of DCL command procedures that perform the SET DEFAULT_G                    and SET PROMPT for you. These DCL command procedures /                    often use a command such as:e  :                    $ set prompt='f$environment("default")'  J                    More advanced users could implement a system service orH                    other intercept, and use these tools to intercept theE                    directory change and reset the prompt accordingly.lB                    (This approach likely involves some kernel-modeD                    programming, and requires write access to various9                    undocumented OpenVMS data structures.)o  J                    There are related tools available from various sources,5                    including the following web sites:c  6                    o  ftp://ftp.hhs.dk/pub/vms/setpmt/  ?                    o  ftp://ftp.tmesis.com/sys_service_hook.src   J                    o  James F. Duff has also made available a Macro32 toolJ                       known as TIME_PROMPT, a tool that sets the prompt to.                       the current system time.  C                    o  Many folks have contributed DCL procedures to E                       perform this task. Visit the newsgroup archives 3                       for information and examples.   D           __________________________________________________________C           8.8  Can I do DECnet task-to-task communication with DCL?e  1                    Yes, you can do this with DCL.   H                    The OpenVMS DECnet documentation shows various simpleI                    examples using the task object and the TYPE command tolH                    trigger the execution of a DCL command procedure on aH                    remote node. An example DCL command procedure that isH                    rather more advanced than using the TYPE command as aB                    trigger is included in the Ask The Wizard area:  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)                      8-8 i  e                              DCL Details        D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availableeF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.u  H                    DCL does not include support asynchronous I/O, thus aJ                    predetermined protocol or a predetermined "turn-around"I                    command sequence must be implemented in order to avoidrJ                    protocol deadlocks-cases where both tasks are trying toH                    write or both tasks are trying to read. The task thatJ                    is writing messages to the network must write (or writeH                    and read) a predetermined sequence of messages, or itI                    must write a message that tells the reader that it can H                    now start writing messages. (This is the essence of a>                    basic half-duplex network protocol scheme.)  D           __________________________________________________________=           8.9  How can I get the width setting of a terminal?T  ;                    $ width = f$getdvi(terminal,"DEVBUFSIZ")w  D           __________________________________________________________9           8.10  Why doesn't DCL symbol substitution work?   E                    The DCL symbol substitution processing occurs onlywD                    at the DCL prompt, not within data and not withinG                    files. If you wish to perform symbol substitution in_E                    this environment, you typically write a small filedD                    containing the command(s) and data to be invoked-D                    potentially only the data-and you then invoke theE                    created procedure or reference the specified data.t  D                    In this case, use of a file containing nolinemodeH                    commands or other techniques might be useful-you willG                    want to ensure that the text editor you use does notuH                    attempt to use screen mode or similar, as this is notE                    generally considered adventageous within a commando                    procedure.i  A                    Tools such as FTP have alternatives: COPY/FTP.d    J                                                                        8-9 e                                 DCL Details        F                    DCL symbol substitution occurs in two passes, usingH                    the ampersand and the apostrophe. In most cases, onlyJ                    the apostrophe is necessary. In a few cases-such as theJ                    DCL PIPE command-you will may need to use the ampersandI                    to get the substitution to work. The following exampledJ                    uses ampersand substitution to transfer the contents of2                    the header into a logical name:  W                    $ PIPE CC/VERSION | (READ SYS$PIPE hdr ; DEFINE/JOB/NOLOG hdr &hdr )   H                    A logical name (in the job logical name table; sharedG                    by all processes in the current job) was used as DCL I                    symbols cannot be returned back out from a DCL PIPE or ,                    other spawned subprocess.  D                    For related materials, please see Section 8.1 and                     Section 8.11.  D           __________________________________________________________7           8.11  How can I substitute symbols in a PIPE?d  E                    Use DCL ampersand substitution, and not apostrophe                      substitution.  M           $ pipe show system | search sys$input opcom | (read sys$input pid ; F               pid=f$element(0," ",pid) ; define/system opcom_pid &pid)           $ show log opcom_pid9               "OPCOM_PID" = "0000020B" (LNM$SYSTEM_TABLE)   D           __________________________________________________________?           8.12  Use of RUN/DETACH, LOGINOUT, and logical names?e  G                    With a command to create a detached process such as:a  K                    $ RUN/DETACHED SYS$SYSTEM:LOGINOUT /INPUT=TEMP_INPUT.COMy  I                    If you are trying to use a logical name as the /INPUT,lB                    /OUTPUT or /ERROR on a RUN/DETACH command, thenE                    you must translate the logical name specifications E                    to physical references before passing them, or the_J                    definitions must reside in a logical name table that is8                    visible to the newly-created process.  F                    Also note that LOGINOUT only creates the SYS$LOGIN,H                    SYS$LOGIN_DEVICE, and SYS$SCRATCH logical names if itI                    is processing a login that is based on the contents ofmJ                    a SYSUAF record-without access to the associated SYSUAFI                    record, this information is not available to LOGINOUT.h                      8-10n o  m                              DCL Details        E                    (If you want to see these particular logical names H                    created, then please specify the /AUTHORIZE qualifier0                    on the RUN/DETACHED command.)  D                    If you do not specify LOGINOUT as the image, thenI                    there is no easy way to get these logical names. Also, F                    any logical names that are used in the target imageD                    file specification must also be in a logical nameE                    table accessible (by default) by the newly-createdeH                    detached process. Shared tables include the group (ifG                    the process is in the same UIC group) and the systemdH                    table. (If the target process is to be in another UICH                    group, a suitablly privileged user or application canG                    create the necessary logical name(s) directly in thee3                    other group logical name table.)i  D                    When in doubt, create a short DCL command file asE                    input, and use a SHOW LOGICAL and similar commandscG                    to examine the context. (And use physical device anduI                    directory references on the RUN/DETACH of the LOGINOUTbG                    image, when specifying this command file as /INPUT.)rD                    Also remember to check both security auditing andG                    system accounting when troubleshooting problems withi"                    the RUN/DETACH.  (                    Also see Section 8.2.  D           __________________________________________________________@           8.13  How to use escape and control characters in DCL?  G                    To write a message and then the bell character, use:b  "                    $ bell[0,7] = 74                    $ write sys$output "Hello''bell'"  /                    To write blinking text, use:d  "                    $ esc[0,7] = 27+                    $ text = "Blinking Text" @                    $ write sys$output "''esc'[5m''text'''esc'[m"  @                    Also see sections Section 11.6, Section 12.1.    J                                                                       8-11                         J                    _______________________________________________________             9        Files      D           __________________________________________________________)           9.1  How can I undelete a file?7  H                    OpenVMS doesn't have an "undelete" function. However,G                    if you are quick to write-protect the disk or if youoJ                    can guarantee that no new files get created or existingE                    files extended, your data is still on the disk and F                    it may be possible to retrieve it. The FLORIAN toolJ                    available from various websites can potentially recoverJ                    the file, see question Section 13.1 for pointers. OtherG                    alternatives here include the DFU tool, available on <                    the OpenVMS Freeware CD-ROM distribution.  H                    If you are setting up a user environment for yourselfJ                    or for others, it is quite easy to use DCL to intercept6                    the DELETE command, using a symbol:  8                    $ DEL*ETE :== @SYS$LOGIN:MYDELETE.COM  @                    The DELETE symbol will cause the procedure toA                    be invoked whenever the user enters the DELETEaG                    command, and it can copy the file(s) to a "trashcan"eE                    subdirectory before issuing a "real" DELETE on thetH                    files. Other procedures can retrieve the file(s) fromJ                    the "trashcan" subdirectory, and can (and should) cleanH                    out the "trashcan" as appropriate. (Realize that thisE                    DELETE symbol can interfere with DELETE/GLOBAL and /                    other similar DCL commands.)e  D           __________________________________________________________I           9.2  Why does SHOW QUOTA give a different answer than DIR/SIZE?e  G                    DIRECTORY/SIZE doesn't take into account the size of F                    file headers which are charged to your quota. Also,G                    unless you use DIRECTORY/SIZE:ALL, you will see onlyeF                    the "used" size of the file, not the allocated sizeG                    which is what gets charged against your quota. Also, ;                    you may have files in other directories._  J                                                                        9-1 e                                 Files        ;                    $ DIRECTORY/SIZE=ALL/GRAND [username...] I                    Grand total of D1 directories, F1 files, B1/B2 blocks.I=                    $ DIRECTORY/SIZZ=ALL/GRAND [-]username.DIRsD                    Grand total of 1 directory, 1 file, B3/B4 blocks.                    $ SHOW QUOTArC                    User [username] has B5 blocks used, B6 availableoP                    of B7 authorized and permitted overdraft of B8 blocks on disk  D                    If the user has no files in other directories andH                    all file-headers are only 1 block, then the following                     should apply:  "                      B5=B2+B4+F1+1  G                    If the diskquota has drifted out of synchronization, H                    then the system-manager can force a quota rebuild-dueE                    to various factors, the quota file can potentially F                    drift from the actual use over time, and a periodicE                    rebuild can be performed at appropriate intervals.d  D                    Also be aware that the DIRECTORY/SIZE command canH                    report larger values than might otherwise be expectedF                    when used to evaluate files and/or directories thatF                    are alias links-such as the system roots on OpenVMSC                    system disks-as the command reports a total thateF                    is cumulative over all of the files and directoriesC                    examined, without regard for which ones might beiF                    alias entries and which are not. (In other words, aG                    DIRECTORY/SIZE of an entire OpenVMS system disk willbF                    report a disk useage value larger than the (usuallyC                    more accurate) value reported by the SHOW DEVICEtI                    command. This as a result of the alias entries linkinglH                    each SYS$SYSDEVICE:[SYSCOMMON]SYS*.DIR directory fileD                    and the SYS$SYSDEVICE:[000000]VMS$COMMON.DIR file                    together.)e  D           __________________________________________________________I           9.3  How do I make sure that my data is safely written to disk?   E                    If your application must absolutely guarantee thataG                    data is available, no matter what, there's really noaI                    substitute for RMS Journaling and host- or controller-VJ                    based shadowing. However, you can achieve a good degreeG                    of data integrity by issuing a SYS$FLUSH RMS call at G                    appropriate times (if you're using RMS, that is.) If I                    you're using a high-level language's I/O system, check                       9-2 n  s                              Files        I                    that language's documentation to see if you can access I                    the RMS control blocks for the open file. In C you can 0                    use fflush followed by fsync.  E                    For details on disk bad block handling on MSCP and H                    on SCSI disk devices, please see Ask The Wizard (ATW)                     topic (6926).  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availablepF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.c  D           __________________________________________________________J           9.4  What are the limits on file specifications and directories?  H                    A file specification has an aggregate maximum size ofE                    255 characters (NAM$C_MAXRSS) at present, assumingrC                    ODS-2 limits and traditional DCL process parsingeC                    settings (SET PROCESS/PARSE_STYLE). The node anduI                    device specification may be up to 255 characters each-cF                    file name and file types may be up to 39 charactersG                    each. File versions are from 1 through 32767, thougheG                    0 (latest version), -0 (oldest version) and -n (n'thzI                    previous version) can be used in most contexts. A filerI                    specification may not have more than 8 directories and I                    subdirectories or-with a rooted directory, two sets of H                    eight are possible-and while it is possible to createH                    subdirectories of greater depth, accessing them underH                    ODS-2 is somewhat problematic in most cases, and thus%                    should be avoided.   =                    Under ODS-5 with extended DCL parsing (SETbC                    PROCESS/PARSE_STYLE), the filename length limitsyF                    are up around 4,095 (NAML$C_MAXRSS) characters, and=                    directories can be around 255 levels deep.e      J                                                                        9-3 e  f                              Files        E                    Application developers should use OpenVMS-supplied J                    routines for parsing file specifications - this ensuresE                    that changes in what is allowable will not tend tofI                    break your application. Consider that various parts ofSI                    the file specification may contain quoted strings with G                    embedded spaces and other punctuation! Some routines H                    of interest are SYS$FILESCAN, SYS$PARSE and LIB$TRIM_E                    FILESPEC. For further information, see the OpenVMS .                    Guide to File Applications.  A                    Performance of larger directory files improveswF                    (greatly) with OpenVMS V7.2 and later-operations onG                    directory files of 128 blocks and larger were rather H                    slower on earlier OpenVMS releases due to the smallerG                    size of the directory cache and due to the directoryS(                    I/O processing logic.  F                    For fastest directory deletions, consider a reverseI                    deletion-delete from the last file in the directory torI                    the first. This reversal speeds the deletion operationaF                    by avoiding unnecessary directory I/O operations asH                    the files are deleted. Tools such as the Freeware DFUI                    can be used for this purpose, as can various availabled9                    reverse-DELETE DCL command procedures.o  )                    Also see Section 5.44.o  D           __________________________________________________________G           9.5  What is the largest disk volume size OpenVMS can access?r  @                    One Terabyte (TB; 2**31 blocks of 2**9 bytes;D                    0x07FFFFFFF blocks). 255 volumes in a volume set.E                    The largest contiguous allocation possible for anyb9                    particular file is 0x03FFFFFFF blocks.   H                    Prior to the release of V6.0, the OpenVMS file systemH                    was limited to disk volumes of 8.38 GB (2**24 blocks,,                    16777216 blocks) or less.  I                    On some systems, there are restrictions in the consolebJ                    program that limit the size of the OpenVMS system disk.C                    Note that data disks are not affected by consoleuB                    program limits. For example, all members of theF                    VAXstation 3100 series are limited to a system diskH                    to 1.073 GB or less due to the console, though largerF                    data disks are possible. This limit due to the SCSI                      9-4 o  s                              Files        I                    drivers used by and built into the console ROM to readsJ                    the OpenVMS bootstrap files, and these same drivers areF                    also used by OpenVMS to write the system crashdump.  D                    There are numerous discussions of this VAXstationE                    3100 in the comp.os.vms newsgroup archives. Please I                    use Google newsgroup search to search the archives for G                    further details, for discussions of the workarounds, G                    and for details of the potential for a simple failed D                    bootstrap and particularly for discussions of theB                    potential for severe system disk corruptions on                    crashes.T  C                    Some SCSI disks with capacities larger than 8.580H                    gigabytes (GB) will require the use of an OpenVMS ECOE                    kit (eg: ALPSCSI04_062 or later; see Section 14.25fG                    for details) for new SCSI device drivers. Failure toaG                    use this ECO can cause "rounding errors" on the SCSIbH                    disk device capacity-OpenVMS will not use nor displayG                    the full capacity of the drive-and "%sysinit-e-error F                    mounting system device status equals 000008C4" (8C4G                    -> "%SYSTEM-?-FILESTRUCT, unsupported file structure G                    level") errors during bootstrap. (One workaround for H                    the bootstrap when the bitmap is located far into theI                    disk is the use of INIT/INDEX=BEGIN.) The problem here I                    involves the particular extensions and fields used for G                    larger capacity disks within the SCSI specifications A                    and within the various intepretations of same.   -                    For ATA (IDE) disk drives:o  J                    o  Versions of SYS$DQDRIVER *BEFORE* X-15 topped out at                       8.455 GB.   G                       Fixed drivers (equal or greater than "X-15") were !                       shipped in:N  7                      o  OpenVMS Alpha V7.2-1, and laterc  7                      o  V7.2 UPDATE V1.0 ECO, and laterr  9                      o  V7.1-2 UPDATE V1.0 ECO, and later   9                      o  V7.1-2 UPDATE V3.0 ECO, and later   J                                                                        9-5    $                              Files        H                    o  The newer SYS$DQDRIVER driver operates to disks upH                       to 33 GB without (known) problems, and effectivelyE                       works with rather larger disks (up to circa 137 G                       GB) but is known to report an incorrect number ofU9                       "cylinders" with disks above 33 GB.2  G                    See Section 14.4.4.2 for additional ATA SYS$DQDRIVER                     information.   E                    Be aware that a known restriction in certain olderhJ                    versions of the Alpha SRM Console prevents booting mostF                    ATA (IDE) drives larger than 8.455 GB, depending onE                    exactly where the various files are located on theBD                    volume. Updated SRM consoles for systems with SRMG                    and ATA (IDE) drive support are (will be) available.1E                    (OpenVMS Engineering has successfully bootstrappednI                    20GB ATA (IDE) disks using the appropriate SRM consoleh                    version.)  1                                              Note   A                       All disk-related listed in this section are D                       stated in units of "disk (base ten) gigabytes"G                       (1 GB = 10^9 bytes) and not in units of "software @                       (base two) gigabytes" (1 GB = 2^30; 1 GB =F                       1073741824.) bytes. Please see Section 14.25 forC                       details of the nomenclature and of the units.o  I                    Be aware that larger disks that are using an extension D                    of SCSI-2- disks that are using a mode page fieldG                    that the SCSI-2 specifications normally reserved foriH                    tape devices-to permit a larger disk volume size willE                    require a SCSI driver update for OpenVMS, and thisBG                    change is part of V7.1-2 and later, and also part ofrE                    ALPSCSI07_062 and later. (These larger disks disks I                    will typically report a DRVERR, or will see the volume H                    size "rounded down".) SCSI disks larger than 16777216J                    blocks cira 8.455 GB (base ten); 8GB (base two) requireJ                    this ECO, or require the use of OpenVMS Alpha V7.1-2 or                    later.   C                    Applications written in C can be limited to file F                    sizes of two gigabytes and less, as a result of theG                    use of longword values within C file operations, and D                    specifically off_t. This restriction is lifted inH                    OpenVMS V7.3-1 and later, and with the application of                      9-6 b                                 Files        J                    the C ECO kits available for specific earlier releases.I                    The use of a longword for off_t restricts applications G                    using native C I/O to file sizes of two gigabytes or I                    less, or these applications must use native RMS or XQP 1                    calls for specific operations.f  9                    Also see Section 14.13, Section 14.25.   D           __________________________________________________________E           9.6  What is the maximum file size, and the RMS record sizeo                limit?a  E                    RMS can store individual files of a size up to theaH                    maximum supported volume size. Under OpenVMS V6.0 andG                    later, the volume size and the RMS maximum file sizeSB                    limit is 2**31 * 512 bytes-one terabyte (1 TB).  D                    "Use a volume set to provide a large, homogeneousI                    public file space. You must use a volume set to create D                    files that are larger than a single physical diskH                    volume. (The file system attempts to balance the loadI                    on the volume sets, for example, by creating new filesaF                    on the volume that is the least full at the time.)"  H                    "You can add volumes to an existing volume set at anyI                    time. The maximum number of volumes in a volume set is I                    255." Further, with a 255 member bound-volume set, the F                    theoretical maximum limit of files is 4,261,478,145B                    files, less the directories and reserved files.  E                    The RMS formats-sequential, relative, and indexed- G                    are limited by the one terabyte maximum volume size. H                    RMS relative files are further limited to a number ofF                    records that will fit in 32 bits-4 billion records.F                    Sequential and indexed formats do not have a record                    limit.t  :                    Also see Section 2.17.1, Section 14.25.            J                                                                        9-7 a  s                              Files      D           __________________________________________________________D           9.7  How do I write CD-Recordable or DVD media on OpenVMS?  F                    How to create CD-R, CD-RW, DVD-R, DVD+R, DVD-RW, or+                    DVD+RW media on OpenVMS?m  H                    For information on CD and DVD optical media drives onH                    OpenVMS, please see Section 14.29. For information onH                    the creation of OpenVMS media and of OpenVMS bootableG                    media, a full step-by-step sequence is documented in_J                    the OpenVMS Ask The Wizard topic (9820). An abbreviated<                    version of the sequence is included here.  B                    Recording (writing) of CD and DVD optical mediaF                    requires a recording or media mastering applicationJ                    or tool, and both commercial and non-commercial optionsE                    are available. For OpenVMS V8.3 and later, see theMI                    COPY/RECORDABLE_MEDIA command available within OpenVMSeH                    itself. Alternatively, please see CDRECORD (both non-G                    DVD and DVD versions are available, and at least one J                    commercial version is available), and also see DVDwriteE                    (commercial) or DVDRECORD (open source). A port of C                    CDRECORD is present in OpenVMS V7.3-1 and later.   H                    o  Acquire a comparatively recent SCSI-based or ATAPIE                       (IDE) CD-R or DVD-R/RW or DVD+R/RW drive. Older H                       drives can be very problematic, while newer drivesI                       are readily available, and are cheap and very fast, E                       and tend to have better compliance with currenteH                       standards. Use of older drives is not recommended.J                       Related device requirements information is available'                       in Section 14.29.   C                    o  Get the most recent LDDRIVER available on theWI                       Freeware, or activate and use the LD version latentmJ                       in OpenVMS Alpha V7.3-1 and V7.3-2 by loading the LDH                       command verb (look within SYS$MANAGER:CDRECORD.COMJ                       for related details), or use the integrated LD found0                       in OpenVMS V8.2 and later.  I                       In particular, you will want to use the current ECOiH                       kit for LDDRIVER (as available), or the version ofH                       LD distributed with V8.2. The OpenVMS V8.2 versionE                       of LDDRIVER was also kitted on Freeware V7.0 as                        LD071.                      9-8 t                                 Files        H                       If you are not running OpenVMS V8.2, the specifiedC                       LD071 kit or later, or a current ECO with theaH                       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 an7G           incompatibility found between older LDDRIVER versions and the            XFC caching support.  C                       As an alternative to LD and LDDRIVER, you caneJ                       acquire and load the VD64 package from the Freeware.  E                    o  Use the COPY/RECORDABLE_MEDIA command available ?                       within OpenVMS V8.3 and later, or use the C                       version of CDRECORD built in V7.3-1 or later,eB                       or obtain and utilize one of the open sourceE                       or commercial versions of the CDRTOOLS/CDRECORDaC                       or DVDRTOOLS/CDRECORD tools, or other similarDD                       recording tools. Freeware V6.0 distribution. (I                       http://www.hp.com/go/openvms/freeware/ ) An OpenVMSII                       port of the cmcd CD audio ripper is also reportedlyo9                       available. http://www.amb.org/xmcd/   J                       Versions of CDRECORD (non-DVD) are latent in OpenVMSD                       Alpha V7.3-1 and later. Commercial versions ofH                       CDDRECORD-with DVD capabilities-are also availableJ                       for various platforms, and particularly a variant ofI                       CDRECORD known as CDRECORD-ProDVD. COPY/RECORDABLE_MA                       MEDIA is built into OpenVMS V8.3 and later.r  ?                       Beware the tool chosen: some versions anddF                       configurations of CDRECORD can record DVD media,I                       as can the DVDRECORD package, as can the commercial H                       DVDwrite package. Many versions of CDRECORD cannotI                       record DVD media, including the version of CDRECORD D                       latent within OpenVMS and the version found onE                       Freeware V6.0; these versions cannot record DVDt                       media.  F                    o  Build the contents of the disk on the LD or VD64'                       device partition.   J                    o  Use the chosen recording tool to record the contentsC                       of the LD or VD64 partition directly onto thet%                       optical medium.a  J                                                                        9-9                                   Files        C                    Alternatively, consider the following command on 2                    OpenVMS Alpha V7.3-1 and later:  1                    @SYS$MANAGER:CDRECORD.COM HELP   H                    While folks have had success getting PC-based CD-R/RWE                    or DVD-R/RW or DVD+R/RW tools to work with OpenVMS H                    partitions, it is far easier and more reliable to useJ                    the OpenVMS-based versions of these tools and directly-I                    attached devices. If you use a Windows-based tool, youoG                    will want to specifically select its raw mode, image I                    mode, or block-copy mode, depending on the terminology D                    within the particular tool. The transfer mode andG                    selections is variously refered to as a disk-at-once H                    (DAO) 2048-byte block ISO Mode 1 raw/image/block data'                    disk recording mode.f  A                    More details: Creation of CD recordable or DVDoD                    recordable media under OpenVMS typically involvesF                    one of two approaches: the use of the optional CD-RJ                    (`Scribe') capabilities available for the InfoServer orG                    other "offline" hardware packages (PC-based packagesoH                    will be included in this), or the use of a host-basedH                    package such as the CDRECORD or COPY/RECORDABLE_MEDIAI                    (V8.3 and later) or other utilities, including OpenVMS J                    ports of common open-source tools made available by Dr.I                    Eberhard Heuser-Hofmann and various others. Commercial G                    packages and options are also available. Dr. Heuser- H                    Hofmann has DVDwrite , a commercial package which canI                    record DVD media. ( http://home.tiscali.de/dvd4openvms                     )  I                    OpenVMS can read ODS-2, ODS-5, and ISO-9660 format CD-rH                    ROMs and DVD-ROMs directly. (If you are very careful,F                    you can create a dual-format CD-R; a CD-R with bothJ                    ODS-2 and ISO-9660 or both ODS-5 and ISO-9660 or both.)  I                    OpenVMS does not support ISO-9660:1999, nor the JolietrH                    or Rock Ridge extensions to ISO-9660, nor can OpenVMS5                    decrypt copy-protected video DVDs.   C                    InfoServer hardware configurations are no longerfE                    available from HP, but may potentially be acquiredvE                    through other means; as used equipment. InfoServerDG                    support also has very specific CD-R recording device-                      9-10                                    Files        D                    prerequisites, and these recording devices are no.                    longer generally available.  H                    Packages related to the use of DVD archiving are alsoF                    available, see the multi-volume capabilities of the/                    DVDarchive/restore Freeware.o  R                    http://www.geocities.com/SiliconValley/Lakes/9999/vmscdwri.html  G                    Additional information is available at the following                     sites:   :                    o  http://www.djesys.com/vms/cdrom.html  J                    o  http://www.cd-info.com/CDIC/Technology/CD-R/vms.html  8                    o  http://www.faqs.org/faqs/cdrom/cd-4                       recordable/part1/preamble.html  2                    o  http://www.tmesis.com/CDrom/  3                    o  http://www.tditx.com/~odsiso/e  G                    U.S. Design offers a package that includes the toolsaI                    necessary to create a CD or DVD-R with either ISO-9660 E                    or ODS-2 format, for standalone CD-R/RW, DVD-R, or H                    DVD+R/RW drives, for recent OpenVMS versions. Details$                    are available at:  .                    o  http://www.usdesign.com/  B                    Also see Section 9.7.2 for details on access to9                    recorded media on older CD-ROM drives.   '           _____________________________k2           9.7.1  CD and DVD notation, terminology?  D                    CD-ROM is pre-recorded Compact Disk media, and isE                    the original and oldest CD format. The original CD I                    media was physically stamped, a recording process thataF                    is now largely reserved to the highest-volume media-                    reproduction requirements.a  E                    CD-R is CD Recordable, a write-once storage mediumsG                    that can be read by all but the oldest of CD drives;VH                    a format which can be read and often even recorded by%                    most CD-RW drives.   J                                                                       9-11 w  p                              Files        H                    CD-RW is CD ReWritable, a format which is readable byI                    many CD drives and by most CD-R drives, and with mediasH                    that can be recorded and re-recorded by CD-RW drives.  G                    CD media recording speeds are listed as multiples ofhF                    150 kilobytes per second, so a 10X drive records atH                    1500 kilobytes (1.5 megabytes) per second. 600 MB (70H                    minutes) and 700 MB (80 minutes) recording capacitiesH                    are both widely available. The minutes designation isF                    derived from the traditional audio-format recording4                    capacity of the particular media.  H                    DVD-R/RW is the older of two common Digital VersatileF                    Disk recording formats, and the DVD-R Recordable orJ                    DVD-RW ReWritable media can be read by many DVD drives.E                    As with CD-R formats in older CD drives, older DVDoI                    and particularly first-generation DVD players may have 6                    problems reading this media format.  B                    DVD+R/RW is the newer of the two common DigitalB                    Versatile Disk recording formats, and the DVD+RD                    Recordable or DVD+RW ReWritable media can be readD                    by many DVD drives. Akin to DVD-R/RW media, olderH                    and particularly first-generation DVD drives can have6                    problems reading this media format.  F                    The DVD Plus-series drives and media tend to recordD                    faster than Minus drives, as (as of this writing)F                    the Plus (+) drives do not require an initial mediaI                    formatting pass and the Minus (-) drives do. While thebG                    appropriate Plus (+) or Minus (-) DVD raw media mustRE                    be chosen for the particular DVD recorder (and DVDDH                    recording drives that are compatible with and capableE                    of using both Plus and Minus media are available),oE                    the resulting recorded media is generally readable)G                    (playable) in all recent DVD drives and DVD players, H                    regardless of type. (Compatibility is best within theF                    same media-series devices of course, but be certainG                    to verify compatibility across devices regardless ofDF                    the particular device or particular recording media                    chosen.)n                          9-12  i  l                              Files        F                    Presently Plus (+) media is slightly more expensiveD                    than Minus (-), but with the prices of all CD andE                    all DVD media continuing to consistently fall, theeI                    differences in DVD media costs are becoming irreleventiD                    for all but the production of huge volumes of DVD                    media.r  J                    The rated DVD recording speeds are in multiples of 1353G                    kilobytes per second, thus a DVD 1X drive is roughlytF                    equivalent to a CD 9X drive in I/O requirements and"                    transfer speed.  H                    DVD drive recording speed can and does vary. DVD diskJ                    drive recording speed is limited by the rated recordingG                    speed of the media used, so the slower (and cheaper) I                    DVD media will not record any more quickly in a fastereD                    drive. A 2.4X DVD drive loaded with 1X media will                     record at 1X.  '           _____________________________iI           9.7.2  Use of RRD42 and other older (embossed-media) CD drives?   I                    The RRD42 series SCSI CD-ROM drive is sufficiently old F                    that it can have problems processing CD-R and CD-RWF                    media. Other very old CD drives can have equivalentG                    media compatibility problems when attempting to read I                    (much) newer CD media and newer CD media technologies. G                    These older CD drives are generally intended for use F                    with the so-called embossed media, rather than withI                    non-embossed recorded (recordable) media now in common                     circulation.   G                    Please consider using a slightly-less-ancient CD-ROMdH                    or CD-R or CD-RW drive when working with non-embossed%                    recorded CD media.   E                    To paraphrase one knowledgable-though deliberately F                    nameless-storage engineer, "The RRD42 drive is just2                    past the drooling idiot stage".          J                                                                       9-13                                   Files      '           _____________________________l?           9.7.3  Creating Bootable OpenVMS I64 CD or DVD Media?                   SYS$SETBOOT?   E                    If you are creating a bootable CD or DVD media foreE                    use with OpenVMS I64, you will want to specify therI                    SYS$SETBOOT block size of 2048, and you will also wantgG                    a disk cluster factor that is a multiple of four via G                    INITIALIZE/CLUSTER=4 (or 8, or...), or you will want E                    to ensure that SYS$EFI.SYS and SYS$DIAGNOSTICS.SYS F                    are aligned to a multiple of four blocks; to a 2048E                    byte boundary. This alignment and this blocking iseI                    only necessary for OpenVMS I64, and only when creating <                    optical media OpenVMS I64 for bootstraps.  I                    The default 512-byte block setting used by SYS$SETBOOTuI                    is the correct and expected value for traditional diskw5                    bootstraps on OpenVMS I64 systems.   G                    Once the boot files are loaded, OpenVMS I64 operatesbH                    with 512-byte blocks; as is the case with ATAPI disksG                    on OpenVMS Alpha, all application code will only seelC                    512-byte blocks on optical media on OpenVMS I64.o  =                    OpenVMS I64 V8.2 and later are expected to A                    have a version of SYS$SETBOOT that will flag adG                    misaligned SYS$EFI.SYS and (if present) a misaligned4,                    SYS$DIAGNOSTICS.SYS file.  G                    For information on SYS$SETBOOT and the SET BOOTBLOCKbA                    command, please see Section 14.3.9 and see theMG                    OpenVMS documentation. The purpose and intent of the F                    SYS$SETBOOT.EXE image and the SET BOOTBLOCK commandF                    is analogous to the WRITEBOOT.EXE image on existing9                    OpenVMS VAX and OpenVMS Alpha systems.e  E                    For information on CD and DVD optical media drivesNG                    on OpenVMS, please see Section 14.29. For additional J                    related information on creating bootable OpenVMS media,:                    please see Ask The Wizard topic (9820).                              9-14                                    Files      D           __________________________________________________________>           9.8  What I/O transfer size limits exist in OpenVMS?  C                    The maximum transfer size is an attribute of thed?                    particular I/O device, controller and driver2E                    combination; there is no inherent limit imposed bybH                    OpenVMS (other than the fact that, today, byte counts>                    and LBNs are generally limited to 32 bits).  F                    The maximum size of a device I/O request is limitedE                    by the value in UCB$L_MAXBCNT, which is set by thesJ                    device driver based on various factors. (Also check theJ                    setting of the MAXBUF system parameter for buffered I/O<                    transfers, and check the process quotas.)  J                    Currently, SCSI drivers limit I/O transfers to FE00(16)E                    bytes, 65024 bytes (decimal). The reasons for thissC                    transfer size limitation are largely historical.lI                    Similarly, DSSI devices are limited to the same value,hG                    this for hardware-specific reasons. Transfers to HSCkD                    and HSJ device controllers via the CI are limitedE                    to 1,048,576 bytes. Client MSCP-served devices are)E                    limited to 65535 bytes-to help ensure that the I/OEI                    fragmentation processing happens on the client and noti(                    on the server system.  G                    Parts of the OpenVMS I/O subsystem are optimized foraE                    data transfers less than 64KB, because (obviously)eJ                    most I/O operations are (substantially) less than that.I                    OpenVMS can handle larger transfers, if the driver andS,                    the device can handle it.  5                    Also see Section 9.4, Section 9.5.   D           __________________________________________________________C           9.9  Can I use ODBC to connect to OpenVMS database files?h  J                    Yes, you can use various available third-party packagesJ                    that permit remote ODBC clients to access RMS files and@                    various commercial databases via the network.  B                    For RMS, consider acquiring one of the packagesF                    available from EasySoft, Attunity Connect (formerlyC                    known as ISG Navigator), Oracle (DB Integrator),_E                    SolutionsIQ, OpenLink Software (OpenLink Universale.                    Data Access), and Synergex.  J                                                                       9-15 C  i                              Files        4                    The unixODBC package available atF                    http://www.unixodbc.org has variously been found to/                    operate on OpenVMS, as well.C  E                    For specific commercial databases (other than RMS,IG                    of course), contact the database vendor directly for                     assistance.  D           __________________________________________________________I           9.10  If my disks are shown as VIOC Compatible, am I using XFC?s  2                    Yes, you are using XFC caching.  I                    Disks that are using XFC caching use communication and F                    coordination protocols that are compatible with theF                    older VIOC caching implementation. With the initialD                    implementation of XFC on OpenVMS, you can use theE                    command SHOW MEMORY/CACHE to see no disks reported_F                    in full XFC mode; all disks shown will be listed in*                    "VIOC Compatable Mode".  I                    If you have the OpenVMS system parameter VCC_FLAGS setFG                    to 2 and are using OpenVMS Alpha V7.3-1 or later, orlG                    are using OpenVMS Alpha V7.3 with the VMS73_XFC V2.0lJ                    ECO kit or later or with the UPDATE kits, you are using                    XFC.   D                    Another confusion: the XFC product version is andI                    remains V1.0 in all released configurations, please do J                    not confuse the internal XFC product version (displayedJ                    by various commands) with the version number associatedH                    with the various ECO kit(s). XFC V1.0 does not permitI                    volumes to enter full XFC caching, as displayed by therJ                    "Vols in Full XFC mode" portion of the DCL command SHOW'                    MEMORY/CACHE output.c  D           __________________________________________________________>           9.11  RMS Sequential Files and Platform Portability?  F                    When working with mixed platforms, you will want toI                    become familiar with the various RMS sequential record H                    formats, including Variable with Fixed Control (VFC),G                    stream, stream LF, and stream CR, among other recordm                    formats.n                      9-16M R  A                              Files        <                    Switching formats uses CONVERT/FDL or SETB                    FILE/ATTRIBUTES. The former converts files, theH                    latter resets attributes. Text editors tend to selectE                    attributes when creating new files that may or mayfF                    not meet requirements. If the default attributes doG                    not match your requirements, create a stub file, SET H                    FILE/ATTR, then edit the existing file. (Most editorsA                    will preserve attributes on an existing file.)/  H                    When working with Windows, stream is usually the bestC                    choice for sequential file operations. Stream LF F                    is most commonly used with UNIX and C applications.H                    Windows and UNIX tend not to be able to directly readG                    files of "unexpected" sequential RMS record formats.   F                    VFC is a common OpenVMS format, encoding the recordI                    length into the record. It is this extra data that can J                    cause corruption-like problems when viewed without RMS;I                    either directly via $qio or via the file system API on J                    other operating system platforms. You will want to lookF                    at the low-level record formats, and at the RMS andJ                    the Files and Applications documentation in the OpenVMS                    manuals.V  C                    If transfering through other platforms, use of arI                    current version of Zip (with the "-Vv" or "-V" option)eE                    and unzip, or use of a BACKUP saveset will containvH                    and maintain the RMS file and record attributes. (ForF                    BACKUP and its own attributes requirements, see the%                    restoration tool.)d  D           __________________________________________________________)           9.12  How to read locked files?   C                    Files can be locked by applications, and various H                    approaches including CONVERT/SHARE and DUMP/ALLOCATEDF                    can be used, as can the following command sequence:  ;                    $ open/read/share=write x lockedfile.txtF                    $ type x   J                    If you can rebuild the application from source, details@                    related to file sharing are in Section 10.17.  J                                                                       9-17 l  c                    J                    _______________________________________________________  2           10       OpenVMS Programming Information      D           __________________________________________________________I           10.1  Modular Programming, Facility Prefixes and Symbol Naming?   G                    Please first review the OpenVMS Programming Concepts G                    Manual and the Guide to Modular Programming manuals. F                    Both are available within the OpenVMS documentationE                    set, and provide details of the expected norms for_$                    OpenVMS programs.  D                    o  Learn about the facility prefix, and use a theJ                       appropriate prefix uniformly throughout all externalG                       symbols, all logical names, and all files locatedwF                       in shared directories. The prefix and the use ofI                       the dollar sign (<$>) and the underscore (<_>) help F                       avoid collisions with other products. Use of theE                       dollar sign is reserved to registered products.   G                    o  Please consider use of tools such as the Freeware H                       SDL package, and the GNM package. These permit youI                       to generate include files and message documentation F                       akin to that of OpenVMS, providing users of your:                       product with a familiar environment.  I                    o  For product installations, consider use of the PCSIfJ                       installation utility, and provide a product-specificB                       configuration DCL command procedure (usuallyE                       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 usually6                       SYS$STARTUP:prefix$SHUTDOWN.COM.  D                    OpenVMS provides a registry for facility prefixesE                    and for MESSAGE message compiler codes. To requestdE                    a prefix and a message facility code for a productoG                    you distributinng to other customer sites, send your   J                                                                       10-1 f  S          2                    OpenVMS Programming Information        F                    request in a mail message addressed to product[-at-J                    sign-]hylndr.sqp.zko.dec.com, requesting the submission@                    form and details of the registration process.  1                                              Note   A                       Please do not request facility prefixes forr@                       products that local to your business, yourA                       site, or your system. Facility prefixes and A                       message codes and the facility registrationtA                       process are intended solely for HP productsgA                       and Partner Products (and yes, even OpenVMS A                       Freeware packages) that will be distributed =                       across multiple OpenVMS customer sites.l  C                    For a list of common coding bugs, please see thecH                    remainder of this section of the FAQ and specificallyJ                    Section 10.22, please also see the Ask The Wizard topicF                    (1661), and for information on debugging an OpenVMS8                    application, please see topic (7552).  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availableiF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.c  D           __________________________________________________________?           10.2  Can I have a source code example of calling...?   J                    Please use the available SEARCH command on OpenVMS, andE                    please remember to search the available resources,AD                    including the support databases and the newsgroupI                    archives. Please also realize that most OpenVMS systemsJ                    services use similar calling sequences, meaning that anJ                    example of calling sys$getjpi can be used as an exampleI                    for sys$getsyi and sys$getdvi. Students: please do not F                    expect folks to write your homework for you. As for$                    search resources:  4                    o  SEARCH SYS$EXAMPLES:*.* target  6                    o  SEARCH TCPIP$EXAMPLES:*.* target                      10-2r i  t          2                    OpenVMS Programming Information        <                    o  http://www.hp.com/go/openvms/freeware/  ,                    o  http://www.google.com/  C                    OpenVMS programming documentation, including the H                    numerous example programs found in recent versions ofI                    the OpenVMS Programming Concepts manual, is available:A  7                    o  http://www.hp.com/go/openvms/doc/P  J                    As for details of argument passing, most OpenVMS systemE                    services and RTL routines pass string arguments by/D                    descriptor. Languages which support native stringE                    data types create descriptors automatically; thoselE                    which do not (eg., C) require that you set them uptG                    explicitly. For further details on using descriptors H                    and particularly for using descriptors from C, please%                    see Section 10.13.f  J                    There is extensive information available on how to callG                    OpenVMS system services and OpenVMS Run-Time LibrarysF                    routines, including examples in numerous languages.;                    Among the best available references are:   1                    o  Your language's User Manual   <                    o  OpenVMS Programming Environment Manual  9                    o  OpenVMS Programming Concepts Manual   F                    o  OpenVMS Programming Interfaces: Calling a System                       Routinea  .                    o  OpenVMS Calling Standard  H                    In addition, you can also locate answers, source codeG                    examples and related discussions in the James Search D                    Assistant (formerly NLSA (Natural Language SearchJ                    Assistant), itself formerly known as Ask Compaq (AskQ))                    database:  F                    o  http://www2.itrc.hp.com/service/james/CPQhome.do  A                    In this area, you will find the source code of @                    programming examples for calls to many of theH                    OpenVMS system services (and from various programming?                    languages), including calls to core services G                    sys$getjpi[w], sys$getsyi[w] and sys$qio[w], as well   J                                                                       10-3 t  s          2                    OpenVMS Programming Information        I                    as source code examples for calls to many other system J                    services and run-time library routines, and examples ofH                    one of the more difficult calling interfaces found onH                    OpenVMS systems, that of the smg$create_menu routine.  G                    Arne Vajhj has put together a collection of OpenVMS 8                    example programs. It can be found at:  /                    o  ftp://ftp.hhs.dk/pub/vms/r  F                    Additional information and examples for OpenVMS are!                    available via:   H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availabletF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for&                    reference. and via:  <                    o  http://www.hp.com/go/openvms/freeware/  D           __________________________________________________________A           10.3  How do I get the arguments from the command line?   A                    If you're writing a program and want to accept I                    arguments from a foreign command, you can use LIB$GET_ I                    FOREIGN to get the command line and parse it yourself,sJ                    or if you're programming in C, use the normal argc/argv                    method.  D                    To write an application which uses the normal DCLF                    verb/qualifier/parameter syntax for invocation, seeF                    the description of the CLI$ routines in the OpenVMS>                    Callable Utility Routines Reference Manual.  F                    It is possible to write an application which can beE                    used both ways; if a DCL verb isn't used to invoke E                    the image, the application parses the command line J                    itself. One way to do this is to call CLI$GET_VALUE forI                    a required parameter. If it is not present (or you getoJ                    an error), call LIB$GET_FOREIGN to get the command line+                    and do the manual parse.n                      10-4                2                    OpenVMS Programming Information        (                    See also Section 8.2.  D           __________________________________________________________E           10.4  How do I get a formatted error message in a variable?   C                    Use the SYS$PUTMSG system service with an actioniJ                    routine that stores the message line(s) in the variableE                    of your choice. Be sure the action routine returnsnC                    a "false" (low bit clear) function value so thateE                    SYS$PUTMSG doesn't then try to display the messageoJ                    (unless you want it to.) See the description of $PUTMSGI                    in the System Services Reference Manual for an example .                    of using an action routine.  D           __________________________________________________________D           10.5  How do I link against SYS$SYSTEM:SYS.STB on an Alpha                 system?n  I                    LINK/SYSEXE is the OpenVMS Alpha equivalent of linking F                    against SYS.STB. This links against the base image:%                    SYS$BASE_IMAGE.EXE   G                    Also see Section 10.11, particularly for pointers toeF                    the details on shareable images and shareable imageH                    creation, and see Section 10.22 for details of inner-G                    mode floating point requirements, of data alignment,aG                    requirements for use of /NOSYSLIB, and other relatedMH                    inner-mode programming details, and see Section 10.111                    for image-related information.S  D           __________________________________________________________@           10.6  How do I do a SET DEFAULT from inside a program?  C                    The problem is that SYS$SETDDIR only changes thenH                    default directory - NOT the default disk. The defaultJ                    disk is determined by the logical SYS$DISK. If you wantI                    to change the default disk within a program, then calllF                    LIB$SET_LOGICAL to change the logical SYS$DISK. YouI                    will need to call both LIB$SET_LOGICAL and SYS$SETDDIR_I                    to change both default disk and the default directory!         J                                                                       10-5 u  d          2                    OpenVMS Programming Information      D           __________________________________________________________I           10.7  How do I turn my Fortran COMMON into a shareable image on                  Alpha?  F                    You need to add SYMBOL_VECTOR=(<common-name>=PSECT)G                    to your options file. On OpenVMS VAX all OVR/REL/GBLlH                    psects were automatically exported into the shareableI                    image's Global Symbol Table. On OpenVMS Alpha you have F                    to tell the linker that you want this done by meansI                    of the PSECT keyword in the SYMBOL_VECTOR options filey                    statement.e  G                    This has several advantages over OpenVMS VAX. First,MI                    you don't have to worry about the address of the psectOD                    when you try to create a new, upwardly compatibleJ                    version of the shareable image. Second, you can controlE                    which psects, if any, are made visible outside thee#                    shareable image.   F                    By default, COMMON PSECTs in HP Fortran for OpenVMSH                    Alpha (as well as most other OpenVMS Alpha compilers)H                    are NOSHR. On VAX, the default was SHR which requiredE                    you to change the attribute to NOSHR if you wantedcH                    your COMMON to be in a shareable image but not write-H                    shared by all processes on the system. If you do want&                    write-sharing, use:  .                    CDEC$ PSECT common-name=SHR  I                    in the Fortran source code (the CDEC$ must be begin inpJ                    column 1) or a linker options file PSECT_ATTR statement<                    to set the COMMON PSECT attribute to SHR.  B                    For further information, see the Linker manual.  D           __________________________________________________________D           10.8  How do I convert between IEEE and VAX floating data?  F                    In OpenVMS V6.1 and later, the routine CVT$CONVERT_C                    FLOAT is documented in the LIB$ Run-Time Library$C                    Reference Manual, and can perform floating pointfH                    conversions between any two of the following floatingH                    datatypes: VAX (F,D,G,H), little-endian IEEE (single,I                    double, quad), big-endian IEEE (single, double, quad),_0                    CRAY and IBM System\370, etc.                      10-6                2                    OpenVMS Programming Information        I                    HP Fortran (all OpenVMS platforms) has a feature which C                    will perform automatic conversion of unformatted B                    data during input or output. See the HP FortranG                    documentation for information on "non-native data in @                    I/O" and the CONVERT= OPEN statement keyword.  B                    There are floating-point conversion source code<                    packages available for various platforms.  G                    For further floating-point related information, see:f  M                    o  http://www.hhs.dk/anonymous/pub/vms/collection/ieee.zipo  D           __________________________________________________________E           10.9  How do I get the argument count in a Fortran routine?t  E                    On VAX, many programmers would use a MACRO routinewB                    which accessed the AP register of the caller toE                    get the address of the argument list and hence the J                    argument count. This was not guaranteed to work on VAX,F                    but usually did. However, it doesn't work at all onF                    OpenVMS Alpha, as there is no AP register. On AlphaJ                    systems, you must use a language's built-in function toJ                    retrieve the argument count, if any. In Fortran this isG                    IARGCOUNT, which is also available in DEC Fortran on                     OpenVMS VAX.   F                    Note that omitting arguments to Fortran routines isC                    non-standard and is unsupported. It will work indF                    many cases - read the DEC Fortran release notes for*                    additional information.  D           __________________________________________________________H           10.10  How do I get a unique system ID for licensing purposes?  B                    Many software developers desire to use a uniqueF                    hardware ID to "lock" a given copy of their productF                    to a specific system. Most VAX and Alpha systems doF                    not have a unique hardware-set "system ID" that canG                    be used for this purpose. HP OpenVMS products do notmE                    use hardware IDs in the licensing methods, as many_I                    users consider a hardware-based licensing scheme to beoJ                    negative attribute when considering software purchases.  J                                                                       10-7               2                    OpenVMS Programming Information        E                    HP OpenVMS uses a software-based system called the C                    License Management Facility (LMF). This provides C                    for software keys (Product Authorization Keys or F                    PAKS) which support capacity and user-based licenseC                    checking. HP offers an LMF PAK Generator to DSPPeG                    (formerly CSA) members-see Section 2.8.3 for general J                    details on the DSPP offerings, and on the DSPP-providedG                    Freeware PAKGEN PAK that is available for those thateG                    are interested in details. (Sorry, no; you can't useeH                    the Freeware PAKGEN PAK to generate any PAK you mightD                    want. Folks at HP also thought of that one, too.)  I                    For information on licensing, please see Section 12.4.   G                    However, if a hardware-based method is required, the E                    most common method is based on an Ethernet adaptor H                    hardware address. Sample source code for implementing(                    this is available at:  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)  D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the available F                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.l  D           __________________________________________________________H           10.11  What is an executable, shareable, system or UWSS image?  B                    Executable code in OpenVMS typically resides inD                    an image-an image is a file-the file extension isG                    typically .EXE-that contains this code. Common typeshI                    of images include executable images, shareable images,u>                    system images, and protected (UWSS) images.  F                    Executable images are programs that can be directlyH                    executed. These images can grant enhanced privileges,G                    with an INSTALL of the image with /PRIVILEGE, or caniD                    grant enhanced access with the specification of aF                    subsystem identifier on the ACL associated with the                    image.                       10-8l m  s          2                    OpenVMS Programming Information        E                    Shareable images contain code executed indirectly,tE                    these images are referenced from executable imagesnG                    and/or from other shareable images. These images can/F                    not grant enhanced privileges, even with the use ofE                    INSTALL with /PRIVILEGE or a subsystem identifier.sF                    These shareable images can be dynamically activatedE                    (a LINK that occurs at run-time) via the LIB$FIND_ D                    IMAGE_SYMBOL run-time library (RTL) routine. (SeeD                    `protected images' for information on `privileged&                    shareable images'.)  D                    System images are intended to run directly on theH                    VAX or Alpha hardware-these are normally used for theB                    kernel code that comprises an operating system.  J                    Protected images-also refered to as User-Written SystemI                    Services (UWSS), or as privileged shareable images-areuH                    similiar in some ways to a standard shareable images,H                    but these images include a `change mode' handler, andI                    execute in an `inner' processor mode (privileged mode; J                    executive or kernel), and code executing in inner modesH                    has implicit SETPRV privilege. Must be INSTALLed withG                    /PROTECT. Note that inner-mode code has restrictions J                    around calling library routines, around calling variousF                    system services, and around calling code located in7                    other protected or shareable images.e  I                    Loadable images and device drivers are images that canoG                    be used to add code into the OpenVMS kernel. Pseudo-rF                    device drivers are a particularly convenient way toF                    add executable code, with associated driver-definedF                    data structures, into the kernel. The pseudo-deviceI                    driver includes the UCB and DDB data structures, and a I                    calling interface with support for both privileged and H                    unprivileged access to the driver code via sys$qio[w]                    calls.   D                    A cookbook approach to creating OpenVMS shareable2                    images is available at the URL:  H                    o  http://www.hp.com/go/openvms/wizard/ (retired; use"                       ITRC forums)    J                                                                       10-9 u  r          2                    OpenVMS Programming Information        D                    For additional information on the OpenVMS Ask TheG                    Wizard (ATW) area and for a pointer to the availablecF                    ATW Wizard.zip archive, please see Section 3.8. ATWF                    has been superceded (for new questions) by the ITRCD                    discussion forums; the area remains available for                    reference.   D           __________________________________________________________8           10.12  How do I do a file copy from a program?  H                    There are several options available for copying filesG                    from within a program. Obvious choices include using G                    lib$spawn(),  system(), sys$sndjbc() or sys$creprc() J                    to invoke a DCL COPY command. Other common alternativesF                    include using the callable convert routines and theE                    BACKUP application programming interface (V7.1 and_                    later).  D           __________________________________________________________&           10.13  What is a descriptor?  B                    A descriptor is a data structure that describesA                    a string or an array. Each descriptor containsrH                    information that describes the type of the data beingD                    referenced, the size of the data, and the addressE                    of the data. It also includes a description of thenJ                    storage used for the data, typically static or dynamic.7                    Descriptors are passed by reference.1  C                    The following are examples of creating and usingtG                    descriptors in C, with the use of the angle bracketsc@                    normally expected by the C include statements=                    deliberately altered in deference to HTML:z  +                        #include {descrip.h} 0                        #include {lib$routines.h}*                        #include {stsdef.h}#                        int RetStat; *                        char TxtBuf[TXTSIZ]8                        struct dsc$descriptor StaticDsc =C                          { 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL }; 5                        struct dsc$descriptor DynDsc =aC                          { 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };t+                        int DynDscLen = 255; C                        $DESCRIPTOR( ConstDsc, "This is a string" );                       10-10               2                    OpenVMS Programming Information        B                        /* finish setting up a static descriptor */<                        StaticDsc.dsc$w_length      = TXTSIZ;E                        StaticDsc.dsc$a_pointer     = (void *) TxtBuf;e  C                        /* finish setting up a dynamic descriptor */CE                        RetStat = lib$sget1_dd( &DynDscLen, &DynDsc ); =                        if ( !$VMS_STATUS_SUCCESS( RetStat ) ) (                          return RetStat;  8                        /* release the dynamic storage */:                        RetStat = lib$sfree1_dd( &DynDsc );;                        if (!$VMS_STATUS_SUCCESS( RetStat ))=(                          return RetStat;  F                    Static descriptors reference storage entirely underG                    application program control, and the contents of thebH                    descriptor data structure can be modified as requiredG                    (by the application). OpenVMS routines do not modify I                    the contents of a static descriptor, nor do they alter D                    the address or length values stored in the staticJ                    descriptor. (The term "static" refers to the descriptorE                    data structure, and not necessarily to the storage 1                    referenced by the descriptor.)h  B                    Dynamic descriptors reference storage under theG                    control of the run-time library, and the contents ofrH                    a dynamic descriptor data structure-once initialized-I                    can only be modified under control of run-time librarytJ                    routines. The dynamic storage referenced by the dynamicI                    descriptor is allocated and maintained by the run-timetF                    library routines. Various OpenVMS routines do alterJ                    the contents of the descriptor data structure, changingJ                    the value for the amount and the address of the storageG                    associated with the dynamic descriptor, as required. J                    Routines can obviously access and alter the contents of<                    the storage referenced by the descriptor.  E                    OpenVMS languages that include support for stringsmD                    or arrays are expected to use descriptors for theE                    particular structure. Most OpenVMS languages, such A                    as Fortran and BASIC, use descriptors entirelysJ                    transparently. Some, like DEC C, require the programmerD                    to explicitly create and maintain the descriptor.  J                                                                      10-11 .             2                    OpenVMS Programming Information        E                    For further information on string descriptors, see G                    the OpenVMS Programming Concepts manual, part of the -                    OpenVMS documentation set.r  D                    Fortran defaults to passing integers by referenceD                    and characters by descriptor. The following sitesG                    discuss mixing Fortran and C source code in the same                     application:   I                    o  http://www.hhs.dk/anonymous/pub/vms/misc/FORTRAN_C_                        CALL.COM  F                    o  ftp://ftp.hhs.dk/pub/vms/misc/FORTRAN_C_CALL.COM  D           __________________________________________________________B           10.14  How do I create a process under another username?  J                    Many server processes can operate within the context ofE                    the target user using privileges, using calls suchsD                    as sys$chkpro and (more commonly in this context)J                    sys$check_access as needed to determine if access wouldI                    be permitted for the specified user within the currentM"                    security model.  B                    With OpenVMS V6.2 and later, the persona systemE                    services (SYS$PERSONA_*) can be used to assume theoJ                    persona of the specified user-these allow the server toJ                    operate as the specified user, in a controlled fashion.I                    The persona services can be used as a "wrapper" aroundeH                    a sys$creprc process creation call, as well-this willG                    create a seperate process entirely under the assumed                     persona.   I                    Information on the persona system services is included*B                    in the OpenVMS V6.2 new features documentation,D                    and in the OpenVMS V7.1 and later system servicesE                    documentation. These system services exist and areo@                    supported in OpenVMS V6.2 and later releases.  J                    Typical mechanisms for creating a process under another$                    username include:  E                    o  personna services around a sys$creprc call. Seei                       above.                      10-12  