›10m›?20 J ›13m 06-May-1988 MDMLIB User's Guide Matthew Madison Center for Interactive Computer Graphics Rensselaer Polytechnic Institute Troy, New York Introduction MDMLIB is a set of miscellaneous routines used in various projects I've worked on. The routines include a set of RMS interface routines for using simple sequential files, a routine to make date/time strings that are compliant with RFC 822, a routine that interfaces with the $TRNLNM system service, and a routine for performing character conversions. Most of these routines are very similar to routines 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). I developed the MDMLIB routines generally because the extant routines and I/O constructs did not provide exactly the service I required. Using MDMLIB I have tried to write the MDMLIB routines so that they would be callable from any language. As I use them mostly from PL/I, I have a library of source inserts that declare the routines and the constants they use for use from PL/I. This file is called PLIMDM.TLB. Users of other languages should be able to decipher the appropriate calling sequences and constant values from this file and from the routine descriptions which appear later in this document. The library itself is called MDMLIB.OLB, and can be linked with any program. PLIMDM.TLB also contains some preprocessor declarations and procedures to assist in using VMS system services. They are documented at the end of this document. Contacting the Author Comments, suggestions, and questions about MDMLIB can be directed to the author via electronic mail at one of the following addresses: Internet: madison@cicgj.rpi.edu BITNET: madison@rpicicge MDMLIB User's Guide page 2 Copyright Notice COPYRIGHT )<) 1988, RENSSELAER POLYTECHNIC INSTITUTE. ALL RIGHTS RESERVED. Permission is given to redistribute this software for non-commercial purposes provided no there is no charge for the distribution beyond handling and materials costs. DISCLAIMER: This software is provided "as is". Neither the author nor Rensselaer Polytechnic Institute makes any guarantee as to the suitability, usefulness, performance, or security of the software. MDMLIB User's Guide page 3 MDM_CLOSEF MDM_CLOSEF closes a file that was opened with MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_CLOSEF unit )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS unit Unit number of open file, as returned by MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION This routine closes a file that was opened with MDM_OPENF. Warning about unit: This "unit number" is for internal use by MDMLIB routines only, and should not be manipulated by a user program. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES RETURNED )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED MDM_OPENF, MDM_READF, MDM_RWNDF, MDM_WRITEF ROUTINES MDMLIB User's Guide page 4 MDM_MKDATE MDM_MKDATE constructs a date/time string from a VMS date/time stamp. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_MKDATE [fs_date], fmt_date [,fd_len] )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS fs_date A quadword VMS absolute date/time stamp. The fs_date argument is the address of a VMS date/time quadword value. If omitted, the current system date/time is used. fmt_date Character string into which the formatted date is written. The fmt_date argument is the address of a quadword descriptor that points to the character string. fd_len Length of the formatted date/time string. The fd_len argument is the address of a word into which the resultant length of the formatted date/time string is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION MDM_MKDATE constructs a date/time string that complies with the Arpanet RFC 822 date/time specification. The format of the string is: Dow, dd Mmm yy hh:mm:ss zone Where "Dow" is the three-letter abbreviation of the day of the week, "dd" is the day of the month, "Mmm" is the three-letter abbreviation for the name of the month, "yy" is the year (last two digits only), "hh:mm:ss" is the time, and "zone" is a zone specification. Note: This routine assumes that it is in the Eastern time zone operating under the daylight savings time schedule. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION SS$_NORMAL indicates normal successful completion. VALUES Status values from LIB$DAY_OF_WEEK and LIB$SYS_FAO RETURNED are also possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED None. ROUTINES MDMLIB User's Guide page 5 MDM_OPENF MDM_OPENF opens a sequential file for reading or writing. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_OPENF key, fspec, unit [,defspec] [,resspec] )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS key Longword mask indicating operation to be performed. The key argument is a longword mask having one of the following values: Value Meaning MDM_M_READ Open file for reading MDM_M_WRITE Open file for writing fspec File specification of file to be opened. The fspec argument is the address of a descriptor pointing to the character string containing a file specification. unit "Unit number" assigned to opened file. The unit argument is the address of a longword into which a file "unit number" is written. defspec Default file specification to be used. The defspec argument is the address of a descriptor pointing to a character string containing a default file specification to be passed to SYS$OPEN. If omitted, a default file specification of ".DAT" is used. resspec Resultant file specification. The resspec argument is the address of a descriptor pointing to a character string into which the full file specification of the opened file is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION MDM_OPENF provides simplified access to RMS for use with sequential files. Certain assumptions are made by this routine: 1. "Opening a file for writing" means creating a new file that is opened for writing. 2. Files opened for writing have variable-length records (maximum length 512) and carriage-return carriage control (i.e. typical VMS sequential file). MDMLIB User's Guide page 6 3. Files are assumed to be sequential, and have the read-ahead and write-behind options turned on in the FAB when opened. The "unit number" is actually the address of a control structure which should not be manipulated by user programs. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES MDM__INVFUNC indicates invalid value for key. RETURNED MDM__INVFSPEC indicates an invalid file specification was given for fspec, defspec, or resspec (usually file specification too long). Error codes from SYS$OPEN, SYS$CREATE, SYS$CONNECT, LIB$GET_VM, LIB$ANALYZE_SDESC are possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED MDM_CLOSEF, MDM_READF, MDM_RWNDF, MDM_WRITEF ROUTINES MDMLIB User's Guide page 7 MDM_PARSE MDM_PARSE is a simplified interface to the RMS $PARSE service. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_PARSE keymask, fspec, [defspec], result [,reslen] )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS keymask Longword mask indicating action to be performed. The keymask argument is the address of a longword mask that may contain a combination of the following values: Value Meaning MDM_M_NODE Return node specification. MDM_M_DEV Return device specification. MDM_M_DIR Return directory specification. MDM_M_NAME Return file name. MDM_M_TYPE Return file type. MDM_M_VER Return version number. MDM_M_SYNCHK Perform syntax check only. MDM_M_PWD If password appears in a DECnet access specification, leave it unaltered (instead of subsituting the word "password"). MDM_M_NOCONCEAL Fully expand concealed device and root specifications. These values may be ORed together in any combination. fspec File specifcation to be parsed. The fspec argument is the address of a quadword descriptor pointing to a character string that contains a file specification to be parsed by $PARSE. defspec Default file specification. The defspec argument is the address of a quadword descriptor pointing to a character string that contains a default file specification to be applied while parsing. result Results of $PARSE call. The result argument is the address of a quadword descriptor pointing to a character string into which the $PARSE results are written. reslen MDMLIB User's Guide page 8 Length of result. The reslen argument is the address of a word into which the number of characters written into result is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION This routine provides a fairly simple interface to the $PARSE service. You specify which parts of the file specification you want, and those parts, with their punctuation, are returned in result. The SYNCHK, PWD, and NOCONCEAL bits are set for the $PARSE call if you specify them in keymask. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES Status values from SYS$PARSE, LIB$GET_VMS, RETURNED LIB$SCOPY_DXDX, and LIB$ANALYZE_SDESC are possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED None. ROUTINES MDMLIB User's Guide page 9 MDM_READF MDM_READF reads a record from a file opened by MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_READF unit, line [,len] )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS unit Unit number of open file, as returned by MDM_OPENF. line Record read from file. The line argument is the address of a quadword descriptor pointing to a character string into which the record is written. len Length of record. The len argument is the address of a word into which the length of the read record is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION MDM_READF reads in a record from a file opened with MDM_OPENF. Any type of character string descriptor can be used for the line argument; the routine uses RTL string-handling routines to copy the data into the character string. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES RMS$_EOF indicates an attempt to read past the end RETURNED of the file. Other status values from SYS$GET are possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED MDM_OPENF, MDM_CLOSEF, MDM_RWNDF, MDM_WRITEF ROUTINES MDMLIB User's Guide page 10 MDM_RWNDF MDM_RWNDF rewinds a file opened by MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_RWNDF unit )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS unit Unit number of open file, as returned by MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION This routine simply issues a call to the SYS$REWIND RMS service. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES Other status values from SYS$REWIND are possible. RETURNED )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED MDM_OPENF, MDM_CLOSEF, MDM_READF, MDM_WRITEF ROUTINES MDMLIB User's Guide page 11 MDM_STRANS MDM_STRANS is an interface to the MOVTC instruction. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_STRANS func, srcstr, dststr )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS func Translation function to be performed. The func argument is a longword mask containing one of the following values: Value Meaning MDM_M_ASCEBC ASCII-to-EBCDIC translation. MDM_M_EBCASC EBCDIC-to-ASCII translation. MDM_M_ASCPRI ASCII-to-Prime ASCII translation. MDM_M_PRIASC Prime ASCII-to-ASCII translation. srcstr String to be translated. The srcstr argument is the address of a quadword descriptor pointing to the character string to be translated. dststr Result of translation. The dststr argument is the address of a quadword descriptor pointing to the character string into which the translation result is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION This routine translates ASCII to and from EBCDIC as well as "Prime ASCII" (also called "negative ASCII"), which is ASCII with the high-order bit set. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION SS$_NORMAL indicates normal successful completion. VALUES Other status values from LIB$ANALYZE_SDESC, RETURNED STR$GET1_DX, and LIB$SCOPY_DXDX are possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED None. ROUTINES MDMLIB User's Guide page 12 MDM_SYS_TRNLNM MDM_SYS_TRNLNM obtains equivalence names for logical names. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_SYS_TRNLNM lognam, [attr], [tblmask], [acmode], eqvnam [,eqvlen] )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS lognam Logical name to be translated. The lognam argument is the address of a quadword descriptor pointing to the character string containing the logical name to be translated. attr Attributes controlling the search for the logical name. The attr argument is the address of a longword bit mask specifying these attributes. tblmask Mask specifying which tables to search. The tblmask argument is the address of a longword bit mask indicating which table(s) should be searched. Bit number Meaning 3 Process logical name table. 2 Job logical name table. 1 Group logical name table. 0 System logical name table. acmode Access mode to be used in the translation. The acmode argument is the address of a byte specifying the access mode. eqvnam Equivalence name. The eqvnam argument is the address of a quadword descriptor pointing to the character string into which the equivalence name, if found, is written. eqvlen Length of equivalence name. The eqvlen argument is the address of a word into which the length of the equivalence name is written. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION This routine uses the $TRNLNM system service to translate a logical name. You may specify which tables to be searched by setting the appropriate bits in tblmask. The tables are always searched in the MDMLIB User's Guide page 13 following order: process, job, group, system. See the description of the $TRNLNM system service for more information on the attr and acmode arguments. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION SS$_NORMAL indicates normal successful completion. VALUES Status values from LIB$SCOPY_DXDX, LIB$SCOPY_R_DX, RETURNED and SYS$TRNLNM are possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED None. ROUTINES MDMLIB User's Guide page 14 MDM_WRITEF MDM_WRITEF writes a record to a file opened by MDM_OPENF. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  FORMAT MDM_WRITEF unit, line )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RETURNS longword condition value )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  ARGUMENTS unit Unit number of open file, as returned by MDM_OPENF. line Record to be written. The line argument is the address of a quadword descriptor pointing to the character string that represents the record to be written to the file. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  DESCRIPTION For MDM_WRITEF to work, the file must have been opened for writing with MDM_OPENF. Results are unpredictable if the record length exceeds 512 bytes. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  CONDITION RMS$_NORMAL indicates normal successful completion. VALUES Status values from LIB$ANALYZE_SDESC and SYS$PUT are RETURNED possible. )0qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq  RELATED MDM_OPENF, MDM_CLOSEF, MDM_READF, MDM_RWNDF ROUTINES MDMLIB User's Guide page 15 PLIMDM.TLB Inserts Besides delcarations for MDMLIB routines and constants, PLIMDM.TLB contains inserts that assist in using VAX/VMS system services. They are as follows: VMS_TYPES The VMS_TYPES insert contains preprocessor constants that can be used to define PL/I variables with VMS type names. Many of the standard VMS types are defined. S_DESC A handy preprocessor procedure that munges a varying character string into a fixed-length string for passing to a system service that requires a fixed-length character string descriptor. Usage: call routine (S_DESC (varying_string_variable)); ITMLST_DECL Contains preprocessor procedures for declaring a VMS "item_list_3" or "item_list_2" structure. Usage: ITMLST_DECL (item_list_3_variable, item_count); ITMLST2_DECL (item_list_2_variable, item_count); Note that the "item_count" should be the total number of items in the list plus one (for the list terminator). ITMLST_INIT Contains preprocessor procedures for assigning values to item lists declared with ITMLST_DECL, above. Usage: ITMLST_INIT (item_list (n), itmcod, bufsiz, buffer, retlen); ITMLST2_INIT (item_list (n), itmcod, bufsiz, buffer); "n" is the element number in the item list. "itmcod" is the item code, "bufsiz" is the size of the buffer, "buffer" is the name of the buffer (the procedure automatically takes the ADDR (buffer)), and "retlen" is the name of the variable into which the returned length should be written. You may omit any or all of the arguments except the first; zero (or NULL ()) is substituted for absent arguments. Note that you must include the commas, even when omitting arguments. Also note that omitting "itmcod" and "bufsiz" indicates an item list terminator. ›10m ›?20 J