                                              MDMLIB User's Guide                    April 1994    :           This manual contains information about MDMLIB, a<           set of miscellaneous utility routines. The library?           consists of routines for simple file I/O, interfacing ?           to the $PARSE, $ASCTOID, and $TRNLNM system services, 9           manipulating disk quota entries, and performing +           character conversions on strings.           A           Revision/Update Information:  This is a revised manual.                    MadGoat Software                                                                   "           ________________________           12 April 1994              __________1           Copyright 1989, 1994 MadGoat Software.   2           Permission is granted for not-for-profit=           redistribution, provided all source and object code >           remain unchanged from the original distribution, and3           that all copyright notices remain intact.   8           Disclaimer: This software is provided "AS IS".9           The authors, MadGoat Software, Western Kentucky ;           University, and TGV, Inc. make no representations 8           or warranties with repsect to the software and9           specifically disclaim any implied warranties of @           merchantability or fitness for any particular purpose.                 A           _______________________________________________________              Contents  A                 _________________________________________________ A                 PREFACE                                         v   A           _______________________________________________________ A           CHAPTER 1  INTRODUCTION                             1-1   A                 _________________________________________________ A                 1.1   USING MDMLIB                            1-1   A                 _________________________________________________ A                 1.2   CONTACTING THE AUTHOR                   1-1   A                 _________________________________________________ A                 1.3   MADGOAT SOFTWARE MAILING LISTS          1-2     A           _______________________________________________________     &           Part I  ROUTINE DESCRIPTIONS:                 MDM_ASCTOID                          RTN-3:                 MDM_CLOSEF                           RTN-6:                 MDM_DQ_ADD                           RTN-8:                 MDM_DQ_CLOSE                        RTN-10:                 MDM_DQ_OPEN                         RTN-12:                 MDM_DQ_READ                         RTN-14:                 MDM_DQ_REMOVE                       RTN-17:                 MDM_DQ_SET                          RTN-19:                 MDM_MKDATE                          RTN-21:                 MDM_OPENF                           RTN-24:                 MDM_PARSE                           RTN-27:                 MDM_READF                           RTN-30:                 MDM_RWNDF                           RTN-32:                 MDM_STRANS                          RTN-34:                 MDM_SYS_TRNLNM                      RTN-36:                 MDM_WRITEF                          RTN-39    A                                                               iii                A           _______________________________________________________              Preface     =           MDMLIB is a library of routines used by various ECS @           utilities. They were written mainly to simplify access*           to existing VMS system services.  A           The_routines_can_be_grouped_as_follows:________________   A           ______________Sequential_File_I/O_Routines_____________   +           MDM_OPENF             Open a file 7           MDM_READF             Read a record from file 6           MDM_WRITEF            Write a record to file;           MDM_RWNDF             Rewind to beginning of file A           MDM_CLOSEF____________Clsoe_file_______________________   A           __________________Disk_Quota_Routines__________________   ;           MDM_DQ_OPEN           Begin disk quota operations =           MDM_DQ_ADD            Add quota entry to quota file >           MDM_DQ_READ           Read one or more quota entries>           MDM_DQ_SET            Modify an existing quota entry4           MDM_DQ_REMOVE         Remove a quota entryA           MDM_DQ_CLOSE__________End_disk_quota_operations________   A           _________________Miscellaneous_Routines________________   @           MDM_ASCTOID           Convert UIC or identifier string0                                 to numeric value:           MDM_MKDATE            Create an RFC822-compliant0                                 date/time string;           MDM_PARSE             Simplified $PARSE interface ;           MDM_STRANS            ASCII/EBCDIC/negative-ASCII 5                                 character translation =           MDM_SYS_TRNLNM        Logical name translation  la .                                 LIB$SYS_TRNLOG      A                                                                 v                  A           _______________________________________________________       1      Introduction        ;           MDMLIB is a set of miscellaneous routines used in =           various ECS projects. The library includes a set of <           RMS interface routines for using simple sequential=           files, a routine to make date/time strings that are >           compliant with RFC 822, routines that interface with<           the $TRNLNM, $ASCTOID, and $PARSE system services,=           a routine for performing character conversions, and 0           routines for manipulating disk quotas.  =           Most of these routines are very similar to routines 9           that already exist on VAX/VMS, or perform tasks >           that can be accomplished through high-level language@           constructs (such as the file I/O routines). The MDMLIB>           routines were developed generally because the extant=           routines and I/O constructs did not provide exactly             the services required.  L           __________________________________________________________________      1.1    Using MDMLIB  @           The MDMLIB routines be callable from any VAX language;=           just link with library MDMLIB.OLB (or MDMLIB.ALPHA_ @           OLB on Alpha AXP). A BLISS REQUIRE file (BLISSMDM.R32)>           accompanies the library for use of the routines from           BLISS.  L           __________________________________________________________________      1.2    Contacting the Author   ?           Comments, suggestions, and questions about MDMLIB can ?           be directed to the authors via electronic mail at one %           of the following addresses:   7              Hunter Goatley <GOATHUNTER@WKUVX1.WKU.EDU> +              Matt Madison <MADISON@TGV.COM>   A                                                               1-1                     Introduction    L           __________________________________________________________________  (    1.3    MadGoat Software Mailing Lists  ;           MadGoat Software has set up the following mailing <           lists for discussions and support of its products:  (           o  Info-MadGoat@wkuvx1.wku.edu  =              Discussion of MadGoat Software products by users 9              and MadGoat developers. To subscribe, send a               message to:  9                       Info-MadGoat-Request@wkuvx1.wku.edu   =              with the word SUBSCRIBE in the first line of the !              body of the message.   ,           o  MadGoat-Announce@wkuvx1.wku.edu  @              Announcements of new releases and new products from6              MadGoat. To subscribe, send a message to:  ;                     MadGoat-Announce-Request@wkuvx1.wku.edu   =              with the word SUBSCRIBE in the first line of the !              body of the message.   (           o  MadGoat-Bugs@wkuvx1.wku.edu  ;              Address for reporting bugs in MadGoat Software =              products. Please include the name of the package >              and version in the subject header of the message,=              so the report can be more easily directed to the #              appropriate developer.               
           1-2                A           _______________________________________________________     &           Part I  Routine Descriptions  >           This part describes the each of the MDMLIB routines.         A                                                       MDM_ASCTOID       A           _______________________________________________________   9           MDM_ASCTOID-Translate Identifier Name or UIC to                         Identifier  ;           MDM_ASCTOID translates an ASCII identifier or UIC 1           specification into an identifier value.   A           _______________________________________________________              FORMAT  #           MDM_ASCTOID  ascid, ident   A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________              ARGUMENTS            ascid               VMS Usage: char_string%           type:      character string            access:    read only"           mechanism: by descriptor4           ASCII representation of UIC or identifier.             ident              VMS Usage: uic_code (           type:      longword (unsigned)           access:    write only            mechanism: by value 5           Identifier value of UIC or identifier name.   A                                                             RTN-3                     MDM_ASCTOID     A           _______________________________________________________              DESCRIPTION <           This routine uses LIB$TPARSE and $ASCTOID to parse?           and translate an identifier or UIC specification from 6           ASCII into the appropriate identifier value.  ?           A UIC specification or identifier may take any of the            following forms:  >           [g,m]            Group and member specified as octal"                            numbers  <           [alphag,m]       Group as alphanumeric identifier;*                            member in octal  ;           [alphag,alpham]  Group and member as alphanumeric &                            identifiers  >           [alpham]         Alphnumeric identifier for full UIC  4           [octal,*]        Wildcard for entire group  4           [alphag,*]       Wildcard for entire group  ?           [*,*]            Wildcard for all users in all groups   7           alphaid          Plain, ordinary alphanumeric %                            identifier   :           %Xhexnum         Identifier value in hexadecimal  =           These are the forms generally recognized by DCL and            its utilities.                           RTN-4          A                                                       MDM_ASCTOID     A           _______________________________________________________   #           CONDITION VALUES RETURNED   =           SS$_NORMAL            Normal successful completion. 8                                 Other status values from>                                 LIB$TPARSE, LIB$ANALYZE_SDESC,:                                 and $ASCTOID are possible.                                                                    A                                                             RTN-5                     MDM_CLOSEF      A           _______________________________________________________   !           MDM_CLOSEF-Close a file   <           MDM_CLOSEF closes a file that was opened with MDM_           OPENF.  A           _______________________________________________________              FORMAT             MDM_CLOSEF  unit  A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________              ARGUMENTS            handle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value 8           Handle of open file, as returned by MDM_OPENF.  A           _______________________________________________________              DESCRIPTION >           This routine closes a file that was opened with MDM_           OPENF.  ?           Warning about handle: Handles are for internal use by @           MDMLIB routines only, and should not be manipulated by           a user program.              RTN-6          A                                                        MDM_CLOSEF     A           _______________________________________________________   #           CONDITION VALUES RETURNED   ;           RMS$_NORMAL           indicates normal successful +                                 completion.                                                                         A                                                             RTN-7                     MDM_DQ_ADD      A           _______________________________________________________   +           MDM_DQ_ADD-Add a disk quota entry   >           MDM_DQ_ADD adds a disk quota entry to a disk volume.  A           _______________________________________________________              FORMAT  4           MDM_DQ_ADD  dqhandle, ident, permq, overdr  A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________              ARGUMENTS            dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference *           Handle created with MDM_DQ_OPEN.             ident              VMS Usage: uic_code (           type:      longword (unsigned)           access:    read only!           mechanism: by reference ?           UIC code or identifier value for which the disk quota            entry is to be added.              permq   &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only             RTN-8          A                                                        MDM_DQ_ADD       !           mechanism: by reference 3           Permanent disk quota value to be entered.              overdr  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference 3           Overdraft disk quota value to be entered.   A           _______________________________________________________              DESCRIPTION >           This routine adds a new entry in the disk quota file4           for the specified UIC or identifier value.  A           _______________________________________________________   #           CONDITION VALUES RETURNED   =           SS$_NORMAL            Normal successful completion. <                                 Other status value from $QIO>                                 or I/O status returns from the<                                 ACP-QIO interface driver are)                                 possible.                               A                                                             RTN-9                     MDM_DQ_CLOSE      A           _______________________________________________________   )           MDM_DQ_CLOSE-Close disk channel   @           MDM_DQ_CLOSE closes a channel opened with MDM_DQ_OPEN.  A           _______________________________________________________              FORMAT              MDM_DQ_CLOSE  dqhandle  A           _______________________________________________________              RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by valuem  A           _______________________________________________________n             ARGUMENTST           dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    modifye!           mechanism: by references>           Handle created by MDM_DQ_OPEN identifying channel to           be closed.  A           _______________________________________________________              DESCRIPTIONa=           MDM_DQ_CLOSE closes the channel opened with MDM_DQ_ ;           OPEN and deallocates the memory used for the disk            quota structures.                  RTN-10 i       A                                                      MDM_DQ_CLOSEo    A           _______________________________________________________c  #           CONDITION VALUES RETURNEDh  =           SS$_NORMAL            Normal successful completion.s                                                                          A                                                            RTN-11     n               MDM_DQ_OPENe      A           _______________________________________________________e  *           MDM_DQ_OPEN-Open channel to disk  ?           MDM_DQ_OPEN opens a channel to a disk volume for diskr           quota operations.   A           ________________________________________________________             FORMAT  '           MDM_DQ_OPEN  devnam, dqhandle_  A           _______________________________________________________              RETURNS            VMS Usage: cond_value_(           type:      longword (unsigned)           access:    write onlyT           mechanism: by value   A           ________________________________________________________             ARGUMENTS.           devnam              VMS Usage: device_name%           type:      character string_           access:    read only"           mechanism: by descriptor2           Device name of disk device to be opened.             dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    write only_!           mechanism: by reference_7           Handle used to refer to disk for other MDM_DQ            operations.              RTN-12 R  3    A                                                       MDM_DQ_OPEN     A           _______________________________________________________Q             DESCRIPTION =           MDM_DQ_OPEN assigns a channel to the specified disk 9           voolume and allocates the structures needed for :           subsequent disk quota operations. Note that this<           routine does not attempt to determine whether disk+           quotas are enabled on the volume.   >           Note that you must be suitably privileged to perform/           disk quota manipulations on a volume.   A           _______________________________________________________   #           CONDITION VALUES RETURNED   =           SS$_NORMAL            Normal successful completion. 8                                 Other status values from:                                 LIB$GET_VM and $ASSIGN are)                                 possible.                                             A                                                            RTN-13_ _  _               MDM_DQ_READ       A           _______________________________________________________a  -           MDM_DQ_READ-Read a disk quota entryn  =           MDM_DQ_READ reads a disk quota and usage entry fromi           the quota file.n  A           ________________________________________________________             FORMAT  <           MDM_DQ_READ  dqhandle, ident, permq, overdr, usage  +                        [,context, actident]d  A           _______________________________________________________t             RETURNS_           VMS Usage: cond_valuen(           type:      longword (unsigned)           access:    write only_           mechanism: by value_  A           _______________________________________________________              ARGUMENTSa           dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference >           Handle for disk channel, as returned by MDM_DQ_OPEN.             identt             VMS Usage: uic_code_(           type:      longword (unsigned)           access:    read only!           mechanism: by reference ;           UIC or identifier value for the entry to be read.i             RTN-14         A                                                       MDM_DQ_READ8                 permq   &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    write onlyT!           mechanism: by referencev6           Permanent quota value from disk quota entry.             overdr  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    write only !           mechanism: by reference 0           Overdraft value from disk quota entry.             usage_  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    write onlyr!           mechanism: by reference 1           Disk usage value from disk quota entry.              contextt  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    modifyi!           mechanism: by referencee<           Context information for wildcard searches of quota           file.              actident             VMS Usage: uic_code (           type:      longword (unsigned)           access:    write onlys!           mechanism: by referencei<           UIC or identifier value read from disk quota entry!           during wildcard search.h  A                                                            RTN-15e O  u               MDM_DQ_READ     A           _______________________________________________________n             DESCRIPTION >           This routine reads the current quota, overdraft, and:           usage values for the specified UIC or identifier9           value. With the use of the context and actidentB@           arguments, this routine can be called repeatedly for a,           wildcard search of the quota file.  ?           Two types of wildcard searching can be performed. The =           entries for all users in a particular UIC group can =           be obtained by specifying UIC$K_WILD_MEMBER for the_>           member portion of the UIC. The entries for all users<           in all groups can be obtained by specifying UIC$K_@           WILD_GROUP for the group portion of the UIC and UIC$K_8           WILD_MEMBER for the member portion of the UIC.  >           To perform a wildcard search, initialize the context@           variable to zero before the first call to MDM_DQ_READ.?           The actual UIC or identifier read from the quota filei;           is returned in actident. Do not alter the context_<           value after the initial read, and continue reading?           until an error code is returned indicating no furthern           entries.  A           _______________________________________________________G  #           CONDITION VALUES RETURNEDu  =           SS$_NORMAL            Normal successful completion.d  >           SS$_BADPARAM          Wildcard UIC specified without?                                 context and actident arguments. =                                 Other status values from $QIO ?                                 and the QIO-ACP driver are also@)                                 possible.s                       RTN-16    m    A                                                     MDM_DQ_REMOVE       A           _______________________________________________________   1           MDM_DQ_REMOVE-Remove a disk quota entry   ;           MDM_DQ_REMOVE removes a disk quota entry from thee           quota file.e  A           _______________________________________________________e             FORMAT  (           MDM_DQ_REMOVE  dqhandle, ident  A           _______________________________________________________b             RETURNSd           VMS Usage: cond_valuee(           type:      longword (unsigned)           access:    write only_           mechanism: by value_  A           _______________________________________________________              ARGUMENTSi           dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference_*           Handle created with MDM_DQ_OPEN.             identr             VMS Usage: uic_code (           type:      longword (unsigned)           access:    read only!           mechanism: by referenceo?           UIC code or identifier value for which the disk quota_!           entry is to be removed.   A                                                            RTN-17_ _  _               MDM_DQ_REMOVE_    A           _______________________________________________________              DESCRIPTIONr@           This routine removes disk quota entries. Note that the>           entry is removed regardless of whether the usage for2           the specified identifier is zero or not.  A           _______________________________________________________a  #           CONDITION VALUES RETURNEDa  =           SS$_NORMAL            Normal successful completion.s@                                 Other status values from $QIO or@                                 the QIO-ACP driver are possible.                                                                   RTN-18 i  r    A                                                        MDM_DQ_SET       A           _______________________________________________________   .           MDM_DQ_SET-Modify a disk quota entry  @           MDM_DQ_SET sets a new quota and/or overdraft value for2           one UIC or identifier in the quota file.  A           _______________________________________________________n             FORMAT  8           MDM_DQ_SET  dqhandle, ident, [permq], [overdr]  A           _______________________________________________________m             RETURNSd           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write onlym           mechanism: by value   A           _______________________________________________________m             ARGUMENTS            dqhandle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference *           Handle created with MDM_DQ_OPEN.             ident              VMS Usage: uic_code (           type:      longword (unsigned)           access:    read only!           mechanism: by referencef?           UIC code or identifier value for which the disk quotal"           entry is to be modified.  A                                                            RTN-19                     MDM_DQ_SET                 permq   &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by referenceE?           Permanent disk quota value to be entered. If omitted,n0           the permanent quota remains unchanged.             overdr  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only!           mechanism: by reference ?           Overdraft disk quota value to be entered. If omitted, 0           the overdraft value remains unchanged.  A           ________________________________________________________             DESCRIPTION 8           This routine modifies a disk quota entry for a:           specific UIC or identifier value. You can change@           either the permanent quota or overdraft value or both;<           if you omit a value it remains unchanged. Use MDM_?           DQ_REMOVE to remove a disk quota entry from the quota            file.   A           _______________________________________________________e  #           CONDITION VALUES RETURNED   =           SS$_NORMAL            Normal successful completion._@                                 Other status values from $QIO or@                                 the ACP-QIO driver are possible.                       RTN-20         A                                                        MDM_MKDATEo      A           ________________________________________________________  ,           MDM_MKDATE-make RFC822 date string  =           MDM_MKDATE constructs an RFC822-compliant date/timed,           string from a VMS date/time stamp.  A           _______________________________________________________r             FORMAT  3           MDM_MKDATE  [fs-date], fmt-date [,fd-len]   A           _______________________________________________________              RETURNSC           VMS Usage: cond_value_(           type:      longword (unsigned)           access:    write onlyR           mechanism: by valueA  A           _______________________________________________________              ARGUMENTS            fs-date              VMS Usage: date_time(           type:      quadword (unsigned)           access:    read only!           mechanism: by referenceA9           A VMS absolute date/time stamp. If omitted, the_+           current system date/time is used.a             fmt-date              VMS Usage: char_string%           type:      character string            access:    write only_"           mechanism: by descriptor;           Character string into which the formatted date isr           written.  A                                                            RTN-21N                    MDM_MKDATE                 fd-len  "           VMS Usage: word_unsigned$           type:      word (unsigned)           access:    write only_!           mechanism: by reference_8           Length of character string stored in fmt-date.  A           _______________________________________________________              DESCRIPTIONe9           This routine constructs a date/time string that 5           complies with the Internet RFC822 date/time 5           specification. The format of the string is:   )              Dow, dd Mmm yy hh:mm:ss zonea  =           Where Dow is a three-letter abbreviation of the day ;           of the week, dd is the day of the month, Mmm is as>           three-letter abbreviation for the name of the month,@           yy is the year (last two digits only), hh:mm:ss is the?           time of day (using 24-hour notation), and zone is the "           time-zone specification.  <           This routine assumes operation in the Eastern time@           zone under the current daylight savings time schedule.>           You can override this default by defining one of two:           logical names. For systems observing US standard:           daylight savings time, defining the logical MDM_<           TZ_PREFIX to be one of E, C, M, or P (for Eastern,?           Central, Mountain, or Pacific) will cause that letter =           to be prepended to either ST or DT, as appropriate. :           To specify your own time zone string, define the?           logical name MDM_TIMEZONE to be the desired time zone <           specification (such as GMT or "-0500"); it will be@           used without modification. Those logical names must be>           defined in the system logical name table to have any           effect.u                 RTN-22         A                                                        MDM_MKDATE     A           _______________________________________________________   #           CONDITION VALUES RETURNED   ;           SS$_NORMAL            indicates normal successful_>                                 completion. Status values from?                                 LIB$DAY_OF_WEEK and LIB$SYS_FAOh2                                 are also possible.                                                                    A                                                            RTN-23_ _  _               MDM_OPENF_      A           _______________________________________________________y             MDM_OPENF-Open a file   7           MDM_OPENF opens a file for sequential access.   A           _______________________________________________________              FORMAT  ?           MDM_OPENF  key, fspec [,handle] [,defspec] [,resspec]   A           _______________________________________________________              RETURNSb           VMS Usage: cond_valuee(           type:      longword (unsigned)           access:    write only            mechanism: by value_  A           _______________________________________________________Q             ARGUMENTSe
           keyD  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value =           Function code indicating operation to be performed. 3           Key may have one of the following values:_  A           _______________________________________________________MA           Value_________________Meaning__________________________   ?           MDM__EXISTS           Test only for file's existence.   6           MDM__READ             Open file for reading.  6           MDM__WRITE            Open file for writing.  A           MDM__APPEND___________Open_file_for_appending._________-             RTN-24         A                                                         MDM_OPENF       =           If the key value may be ORed with the modifier MDM__=           M_FID, which indicates that the fspec argument is a @           descriptor pointing to a VMS file ID. MDM_M_FID is not*           valid with the MDM__EXISTS  key.             fspecg              VMS Usage: char_string%           type:      character string            access:    read only"           mechanism: by descriptor<           File specification of file to be opened. If MDM_M_<           FID is specified, the descriptor should point to a?           28-byte structure containing the 16-byte device name,r@           6-byte file ID, and 6-byte directory ID of the file to>           be opened (this is the 28 consecutive bytes of a NAM3           block starting with the NAM$T_DVI field).l             handle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    write onlyr!           mechanism: by reference @           "Handle" assigned to opened file, used to identify the?           file for subsequent file operations. This argument is_;           optional only when key has the value MDM__EXISTS.              defspecE              VMS Usage: char_string%           type:      character string            access:    read only"           mechanism: by descriptor<           Default file specification to be used when opening@           the file. If omitteed, a default file specification of           .DAT is used.              resspeci              VMS Usage: char_string%           type:      character string            access:    write only_"           mechanism: by descriptor  A                                                            RTN-25m s  e               MDM_OPENF       ?           If specified, the RMS resultant file specification is             copied to this string.  A           _______________________________________________________              DESCRIPTION =           MDM_OPENF provides simplified access to RMS for use_=           with sequential disk files. Certain assumptions are_           made by this routine:_  >           o  "Opening a file for writing" means creating a new=              file that is opened for writing. "Opening a file >              for appending" means opening an existing file for>              writing and positioning to the end of file before>              the first write operation. Both of these types of>              open operations use exclusive access to the file.  =           o  Read-only operations allow for multiple readers.   ?           o  Files created by this routine have variable-lengths?              records and carriage-return carriage control (i.e. /              typical VMS sequential text file)._  9           The handle is actually the address of a control <           structure used internally by the file I/O routines:           that should not be manipulated by user programs.  A           _______________________________________________________n  #           CONDITION VALUES RETURNED   =           RMS$_NORMAL           Normal successful completion.   6           MDM__INVFUNC          Invalid value for key.  :           MDM__INVFSPEC         Invalid file specification<                                 given for fspec, defspec, or@                                 resspec. Error codes from $OPEN,>                                 $CREATE, $CONNECT, LIB$GET_VM,>                                 and LIB$ANALYZE_SDESC are also)                                 possible.              RTN-26 e  n    A                                                         MDM_PARSE       A           _______________________________________________________   '           MDM_PARSE-Interface to $PARSEe  ?           MDM_PARSE is a simplified interface to the RMS $PARSEn           service.  A           _______________________________________________________l             FORMAT  @           MDM_PARSE  keymask, fspec, [defspec,] result [,reslen]  A           _______________________________________________________t             RETURNS            VMS Usage: cond_value (           type:      longword (unsigned)           access:    write onlye           mechanism: by value   A           _______________________________________________________              ARGUMENTS            keymaskg  "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only!           mechanism: by referencet8           A mask indicating actions to be performed. Any:           combination of the following values may be used:  A           _______________________________________________________ A           Value_________________Meaning__________________________   :           MDM_M_NODE            Return node specification.  <           MDM_M_DEV             Return device specification.  ?           MDM_M_DIR             Return directory specification.a  A                                                            RTN-27d f  a               MDM_PARSEc    A           _______________________________________________________eA           Value_________________Meaning__________________________I  1           MDM_M_NAME            Return file name.$  1           MDM_M_TYPE            Return file type.h  6           MDM_M_VER             Return version number.  8           MDM_M_ALL             Return all parts of file.                                 specification.  :           MDM_M_SYNCHK          Perform syntax check only.  ?           MDM_M_PWD             Leave password in DECnet access 1                                 string unaltered.A  =           MDM_M_NOCONCEAL       Fully expand concealed devicelA           ______________________and_root_specifications._________                fspech              VMS Usage: char_string%           type:      character stringr           access:    read only"           mechanism: by descriptor*           File specification to be parsed.             defspecD              VMS Usage: char_string%           type:      character string            access:    read only"           mechanism: by descriptor>           Default file specification to be used while parsing.             result              VMS Usage: char_string%           type:      character string            access:    write onlyv"           mechanism: by descriptor             RTN-28         A                                                         MDM_PARSE       >           Result of the parsing operation. The result includes>           only those parts of the file specification specified           by keymask.              reslen  "           VMS Usage: word_unsigned$           type:      word (unsigned)           access:    write only_!           mechanism: by reference -           Length of string written to result.l  A           ________________________________________________________             DESCRIPTIONU<           This routine provides a fairly simple interface to<           the $PARSE RMS service. Specify which parts of the9           file specification you want returned, and those_=           parts, written in normal RMS order with appropriate ?           punctuation, are returned in result. The SYNCHK, PWD, ;           and NOCONCEAL options are passed along to $PARSE.y7           Refer to the RMS manual for more information.e  A           _______________________________________________________c  #           CONDITION VALUES RETURNEDu  =           RMS$_NORMAL           Normal successful completion. @                                 Other status values from $PARSE,?                                 LIB$GET_VM, LIB$SCOPY_DXDX, and ?                                 LIB$ANALYZE_SDESC are possible.                     A                                                            RTN-29_ _                  MDM_READF       A           _______________________________________________________   !           MDM_READF-Read a recordh  =           MDM_READF reads a record from a file opened by MDM_o           OPENF.  A           _______________________________________________________O             FORMAT  *           MDM_READF  handle, recbuf [,len]  A           _______________________________________________________s             RETURNS            VMS Usage: cond_valueh(           type:      longword (unsigned)           access:    write only            mechanism: by valuei  A           _______________________________________________________D             ARGUMENTS            handle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valuev8           Handle of open file, as returned by MDM_OPENF.             recbuf              VMS Usage: char_string%           type:      character string            access:    write onlyd"           mechanism: by descriptor>           Character string into which the record read from the           file is stored.M             RTN-30         A                                                         MDM_READF       
           len   "           VMS Usage: word_unsigned$           type:      word (unsigned)           access:    write only !           mechanism: by referencel*           Length of record read from file.  A           _______________________________________________________b             DESCRIPTIONa=           MDM_READF reads in one record from a file opened by :           MDM_OPENF. The RTL character string routines are=           used to copy the record into recbuf, so any type ofe>           character string descriptor that the RTL handles can           be used.  A           _______________________________________________________   #           CONDITION VALUES RETURNED   =           RMS$_NORMAL           Normal successful completion.:  ?           RMS$_EOF              Attempt was made to read beyond @                                 end of file. Other status values<                                 from $GET are also possible.                              A                                                            RTN-31w _  i               MDM_RWNDF       A           _______________________________________________________:             MDM_RWNDF-Rewind file   <           MDM_RWNDF rewinds a file that was opened with MDM_           OPENF.  A           ________________________________________________________             FORMAT             MDM_RWNDF  handleh  A           _______________________________________________________o             RETURNSo           VMS Usage: cond_valuee(           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________              ARGUMENTS            handle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value   A           _______________________________________________________              DESCRIPTION =           This routine simply issues a $REWIND RMS service on0           the file.                      RTN-32         A                                                         MDM_RWNDF_    A           _______________________________________________________g  #           CONDITION VALUES RETURNEDR  =           RMS$_NORMAL           Normal successful completion. @                                 Other status values from $REWIND2                                 are also possible.                                                                      A                                                            RTN-33     g               MDM_STRANS      A           _______________________________________________________   3           MDM_STRANS-Interface to MOVTC instruction_  ;           MDM_STRANS translates character strings using the            MOVTC instruction.  A           _______________________________________________________              FORMAT  *           MDM_STRANS  func, srcstr, dststr  A           _______________________________________________________r             RETURNSi           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write only            mechanism: by value   A           _______________________________________________________h             ARGUMENTSi           func  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by value @           Selects the translation function to be performed. Func/           can have one of the following values:s  A           _______________________________________________________dA           Value_________________Meaning___________________________  <           MDM__ASCEBC           ASCII to EBCDIC translation.  <           MDM__EBCASC           EBCDIC to ASCII translation.  4           MDM__ASCPRI           ASCII to Prime-ASCII,                                 translation.             RTN-34         A                                                        MDM_STRANSf    A           _______________________________________________________rA           Value_________________Meaning__________________________(  4           MDM__PRIASC           Prime-ASCII to ASCIIA           ______________________translation._____________________n               srcstr              VMS Usage: char_string%           type:      character stringu           access:    read only"           mechanism: by descriptor"           String to be translated.             dststr              VMS Usage: char_string%           type:      character strings           access:    write only "           mechanism: by descriptor            Result of translation.  A           _______________________________________________________o             DESCRIPTIONT=           This routine translates between ASCII and EBCDIC asn>           well as between ASCII and "Prime ASCII" (also called@           "negative ASCII"), which is 7-bit ASCII codes with the#           8th bit set in each byte.t  A           _______________________________________________________t  #           CONDITION VALUES RETURNEDy  =           SS$_NORMAL            Normal successful completion. 8                                 Other status values from?                                 STR$GET1_DX, LIB$ANALYZE_SDESC,_@                                 and LIB$SCOPY_DXDX are possible.      A                                                            RTN-35     p               MDM_SYS_TRNLNM      A           _______________________________________________________   5           MDM_SYS_TRNLNM-Interface to $TRNLNM service   @           MDM_SYS_TRNLNM translates logical names using $TRNLNM.  A           _______________________________________________________              FORMAT  >           MDM_SYS_TRNLNM  lognam, [attr], [tblmask], [acmode],  *                           eqvnam [,eqvlen]  A           ________________________________________________________             RETURNS_           VMS Usage: cond_value (           type:      longword (unsigned)           access:    write onlyr           mechanism: by value_  A           _______________________________________________________              ARGUMENTSn           lognam  !           VMS Usage: logical_name %           type:      character string            access:    read only"           mechanism: by descriptor(           Logical name to be translated.             attr  "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only!           mechanism: by referenceu<           Attributes controlling the logical name search, as           used by $TRNLNM.             RTN-36 a  s    A                                                    MDM_SYS_TRNLNMM                 tblmask_  "           VMS Usage: mask_longword(           type:      longword (unsigned)           access:    read only!           mechanism: by referencep:           Mask specifying which tables should be searched.  A           _______________________________________________________p           Bit      Mask A           number___value_____Meaning_____________________________   7             3        8       Process logical name tablem  3             2        4       Job logical name tablei  5             1        2       Group logical name tablec  A           __0________1_______System_logical_name_table___________i  =           If omitted, the logical name tables that defined byg=           logical name LNM$FILE_DEV (which is either in table <           LNM$PROCESS_DIRECTORY or LNM$SYSTEM_DIRECTORY) are           searched.a             acmode              VMS Usage: access_mode$           type:      byte (unsigned)           access:    read only!           mechanism: by referencee?           Access mode to be used in the translation, as used by            $TRNLNM.             eqvnam              VMS Usage: char_string%           type:      character stringl           access:    write only "           mechanism: by descriptor>           String into which the equivalence name is written if           found.  A                                                            RTN-37e s  t               MDM_SYS_TRNLNM                 eqvlen  "           VMS Usage: word_unsigned$           type:      word (unsigned)           access:    write onlyE!           mechanism: by referenceg%           Length of equivalence name.   A           _______________________________________________________              DESCRIPTIONe9           This routine uses the $TRNLNM system service too=           translate a logical name. Only the tables specifiedd:           by the tblmask argument are searched. The tables<           are searched in the following order: process, job,?           group, system. Only the first equivalence name can be :           retrieved with this routine-search lists cannot.  ?           See the description of the $TRNLNM system service fore:           an explanation of the attr and acmode arguments.  A           ________________________________________________________  #           CONDITION VALUES RETURNED   =           SS$_NORMAL            Normal successful completion. 8                                 Other status values from<                                 LIB$SCOPY_DXDX, LIB$SCOPY_R_=                                 DX, and $TRNLNM are possible.n                                   RTN-38    r    A                                                        MDM_WRITEFd      A           _______________________________________________________a  -           MDM_WRITEF-Write a record to a filep  =           MDM_WRITEF writes a record to a file opened by MDM_n           OPENF.  A           _______________________________________________________e             FORMAT  $           MDM_WRITEF  handle, recbuf  A           _______________________________________________________t             RETURNS            VMS Usage: cond_values(           type:      longword (unsigned)           access:    write onlys           mechanism: by valuem  A           ________________________________________________________             ARGUMENTS_           handle  &           VMS Usage: longword_unsigned(           type:      longword (unsigned)           access:    read only           mechanism: by valuee3           Handle of file, as returned by MDM_OPENF.e             recbuf              VMS Usage: char_string%           type:      character string            access:    read only"           mechanism: by descriptor?           Character string containing data to be written to the            file.L  A                                                            RTN-39     T               MDM_WRITEF    A           _______________________________________________________              DESCRIPTION_=           This routine uses the $PUT RMS service to write thef@           record to the file. The file must have been opened for0           writing (or appending) with MDM_OPENF.  A           _______________________________________________________   #           CONDITION VALUES RETURNED   =           RMS$_NORMAL           Normal successful completion._8                                 Other status values from>                                 LIB$ANALYZE_SDESC and $PUT are)                                 possible.o                                                                 RTN-40