.date .subtitle .ps 60,72 .figure 28 .center;GUIDE TO USING FDMP .blank .center;Kenneth A. Randell .chapter Introduction .hl 1 General Information .ap FDMP is a program written to dump and edit FORTRAN unformatted data files. It can handle either segmented or fixed-length records from disk or tape. It will dump records in a variety of ways, including ascii, hex, octal, integer (both I*2 and I*4), byte, single or double precision floating point, binary, or any combination of these. Integer data may be interpreted as signed or unsigned. The program has features such as a SEARCH command, which can scan records for certain values, reversal of byte order upon input, etc. Dumps may be displayed on the terminal, or written to a listing file, or both. There is also a feature which allows the user to take advantage of the scrolling features of a VT100 family terminal when dumping records (similar to and inspired by the same feature in SYSGEN). FDMP can also convert FORTRAN data files from one format to another (fixed length records to segmented, or vice versa, for example). The editing capability of this program is somewhat limited. Values may be replaced or deleted, but not inserted. The user can edit the records he wishes, and upon issuing an EXIT command, a new version of the file will be created, containing the new values. The program is conversational in nature, so that in one run, the user may dump several files, or different parts of one file. Commands may be entered to the fewest significant characters. An on-line help facility is available, as well as the logging of commands in a log file, and the reading in of commands from a previously created file. .hl 1 Program Limitations The user should be aware of several limitations of this program. These include a limitation on the record size of files to be edited (32768 bytes), and the inability to edit records from a magnetic tape. The program will not correctly handle files over the network, as VMS will not allow REWINDs of such files. If necessary, copy the file to the local node, and run FDMP on it there. The program will dump FORTRAN unformatted files created on a PDP-11, although FDMP must be run on a VAX, as it uses VAX system services and library routines. .chapter Commands .hl 1 Format of Commands Commands for FDMP may be entered using the fewest number of characters which make it unambiguous. If FDMP does not understand a command, it will echo the line back to the user, along with an up-arrow (_^) indicating where the error occured. If the command is ambiguous, FDMP will give a message stating this, and ask the user to reenter the command. FDMP does not prompt for missing values, so commands must be completely on one line. Commands may be up to 255 characters in length, and entered in either upper or lower case. FDMP always translates all user input into uppercase, except for that part of the command that is enclosed in double quotation marks ("). FDMP will "swallow" the double quotation marks while leaving the text string inside them alone. The double quotation marks are meant to be used only for search or replacement strings, and not for commands themselves. For example, FDMP understands the command CLEAR entered either as clear (FDMP upcases this), or as CLEAR, but not as "clear" ("CLEAR" is acceptable, but rather redundant). Execution of the commands DUMP and SEARCH may be interrupted at any time by hitting control-C (CNTL-C) on the terminal. .hl 1 FDMP commands FDMP recognizes the following commands. The complete documentation for each command appears in the next section. .blank 1 .nap .list .le;^&CLEAR\& clears the screen of any DEC CRT (VT52, VT55, VT100 family, etc.). .le;^&CONVERT\& converts files from one record type to another. .le;^&DEFINE\& defines macros to be used to dump records from the file. A macro is a string of characters which define how the record is to be dumped (integer, ascii, etc.). .le;^&DISPLAY\& allows the user to turn the display of the contents of the data records on and off. .le;^&DO\& allows the user to execute a DCL command in a sub-process. FDMP uses LIB$SPAWN to execute the command. Note the command may only be 132 characters in length (VMS limitation), although it may contain an at (@) sign to execute a command file. .le;^&DUMP\& dumps a record or range of records from a file. .le;^&ECHO\& allows the user to echo back on the screen commands read in from an input file (see READ). .le;^&EDIT\& allows the user to edit data records in the file. .le;^&EXIT\& creates a new version of the data file being edited. .le;^&FULLSCR\& turns off and on the 'full-screen' dump feature of FDMP. Note that this feature only works on VT100 family terminals. FDMP will detect attempts to do this on a non-VT100 terminal, and will turn FULLSCR off. .le;^&HELP\& retrieves on-line documentation on the commands for the user. .le;^&LOGGING\& turns off and on the logging of commands enter to FDMP in a log file (called FDMP.LOG). .le;^&OPEN\& opens a file for dumping or editing. .le;^&PRINT\& turns off and on the writing of records dumped to an listing file. This file is not actually printed by FDMP. .le;^&QUIT\& exits FDMP without creating a new file even if any editing has been done. .le;^&READ\& reads in commands from an auxilary input file. .le;^&REMOVE\& removes macro definitions from the internal definition table kept by FDMP. Up to 20 macros may be defined at once. .le;^&REVERSE\& reverses bytes in the data records before displaying the contents. Note that REVERSE reverses all bytes, but as far as interpretation of integers go, it is only valid for words (I*2). .le;^&SEARCH\& searches the file for a specified value. .le;^&SHOW\& displays various things about the current state of FDMP, such as the current file name, flag settings, etc. .le;^&SUMMARY\& turns off and on the display of the length of each data record in bytes. .end list .hl 1 Detailed Descriptions .ap Below follows a detailed description of each command, its format, and default values, if applicable, at program start-up. .nap .nf .hl 2 CLEAR .literal FORMAT: CLEAR DEFAULTS: not applicable This command clears the screen of any DEC CRT. These terminals include (but are not limited to) VT52, VT55, and the VT100 family. If the foreign terminal package (SCRFT in the directory SYS$EXAMPLES) has been built, and the user is on a terminal declared as types FT1 through FT8, the program will use the escape sequences defined there to try and clear the screen. This command has no affect on hardcopy terminals, or terminals with a device type of unknown. .end literal .hl 2 CONVERT .literal FORMAT: CONVERT TO FIXED CONVERT TO SEGMENTED CONVERT TO VARIABLE DEFAULTS: none This command converts the OPEN file from one format to another. This command is useful for converting unformatted data files from one type to another. Note that the limit on size of FIXED and VARIABLE records is 32,767 bytes. If converting to FIXED, and the input record is longer than the specified output length, a warning message is issued and the record is truncated at the specified output length. If the input record is shorter than the output specified length, it is padded with bytes with a value of zero (0 decimal). If converting to VARIABLE, and the input record is greater than 32767 bytes, an error is reported, and the input record is ignored (NOT output to the new file). In all cases, the output file created has the same name as the input file with the exception that the file is given an extension of CVT. .end literal .hl 2 DEFINE .literal FORMAT: DEFINE MACRO DEFAULTS: none This command defines a macro to FDMP. A macro is a definition of how FDMP is to interpret values in the data record. All macros have names, which may be up to 255 characters in length, and include the characters A-Z, the numerals 0-9, and underline and dollar sign. Up to 20 macros may be defined at once. Macro names should be significant enough to be unique. If two macros have the same name, the last definition found will be the one that is used. .end literal .hl 3 Macro definitions .literal A macro definition may be from 1-255 characters in length. Its format is similar to a FORTRAN format statement. Commas and blanks may be inserted but are ignored. The carriage return terminates the definition. The definition may also include a repeat operation in parentheses, but only one level is understood. The valid characters in the definition are: X skips one byte in the record A translates 1 byte as ascii, which, if unprintable, will be a '.' B returns a signed byte D returns a double precision (real*8) floating point number F returns a single precision (real*4) number H returns a hexadecimal longword L returns a signed longword O returns a byte in octal W returns a signed word (2 bytes) T returns the VAX system time (8 bytes) There are 2 characters for special interpretation of data fields. These are U and Z. When placed in front of the L, W, or B codes, these codes act as modifiers to the standard interpretation. ZB dumps one byte (8 bits) in binary ZW dumps one word (16 bits) in binary ZL dumps one longword (32 bits) in binary UB dumps one unsigned byte, rather than signed UW dumps one unsigned word, rather than signed UL dumps one unsigned longword, rather than signed Repeat counts may be specified as needed (e.g. 4ZL will dump 4 longwords in binary). Example: Suppose a file has records that have the following things in them: a 9 byte character variable, an unsigned word, one byte of various bit settings, and then 20 triples of one double- precision floating, a hex longword, and one byte in octal. To define this record, one could use the following command (note the commas are optional and are included only for readability): DEFINE MACRO MINE 9A,UW,ZB,20(D,H,O) The user could then dump records 5 through 10 by issuing: DUMP 5:10 USING MINE .end literal .hl 2 DISPLAY .literal FORMAT: DISPLAY ON DISPLAY OFF DEFAULTS: DISPLAY ON Enables or disables the display on the terminal of the contents of the data records being dumped or searched through. Turning the display off and the summary on (see SUMMARY) enables the user to get the length of each dumped record in bytes without having to use a macro definition. .end literal .hl 2 DO .literal FORMAT: DO DEFAULTS: none Allows the user to spawn a sub-process to execute any valid DCL command. Use of this command requires the user have a PRCLM (sub-process create limit) of at least one. Since the spawned process inherits all of the parent's logical names and symbol definitions, on a loaded system this command make take a while to execute. After the command has been executed, control returns to FDMP. Note while this is a handy feature, the spawned command cannot do some things, such as change the default working directory of the parent. The command may include an at (@) sign, in which case a command file will be executed. If the command is not given (i.e., DO is issued with no command), a prompt will be given, asking the user to enter a command. If the call to LIB$SPAWN fails, an error message will be returned. .end literal .hl 2 DUMP .literal FORMAT: DUMP [record-range] [USING ] DEFAULTS: If record-range is not specified, the whole file will be dumped. If USING is not specified, the current macro definition will be used (see SHOW CURRENT). This command performs the actual dumping of data records. A file must be OPENed before it can be dumped. Also, the macro name used must reference a defined macro. If DISPLAY is ON (default), the record contents will be displayed on the terminal. If PRINT is ON (PRINT is OFF by default), the record contents will also be sent to a disk file. Valid formats for record-range are m any single record m:n a range of records. n must be greater than or equal to m. .end literal .hl 2 ECHO .literal FORMAT: ECHO ON ECHO OFF DEFAULTS: ECHO OFF This command enables the user echo lines back to the terminal that are read in from an auxilary command file. It has no affect on user input from the terminal. Commands are echoed as they are read in (i.e., before upcasing, etc.). .end literal .hl 2 EDIT .literal FORMAT: EDIT record-range [USING ] DEFAULTS: None for record-range. If USING is not specified, the current macro definition is used (see SHOW CURRENT). This command invokes the record editing feature of FDMP. Records may be edited in whatever manner the user desires. For more information on the use of EDIT, see the section on editing editing data files in chapter 3 of this manual. .end literal .hl 3 EDIT sub-commands .literal There are several sub-commands that EDIT understands. These are as follows: .end literal .hl 4 ABORT .literal FORMAT: ABORT DEFAULTS: not applicable This command will stop the current editing session. It would be the same as if the user had issued a QUIT while editing the current record, and a QUIT after all other records that would be edited in that session. Note that modifications made to records that have been recorded (via EXIT) are NOT affected. .end literal .hl 4 DELETE .literal FORMAT: DELETE field-range DEFAULTS: none This command will delete specified values from the data record as defined by the current macro. The field range may be in the format one of the following: m single entry m:n contiguous range of entries, with m less than or equal to n. .end literal .hl 4 EXIT .literal FORMAT: EXIT DEFAULTS: not applicable The EXIT command updates a file that is kept of all changes made to the current record. When the user is done editing a data record, he needs to enter the EXIT command to get FDMP to store the updated record in the work file. .end literal .hl 4 QUIT .literal FORMAT: QUIT DEFAULTS: not applicable The QUIT command stops the editing of the current record. If QUIT is issued before an EXIT command, no record of the modifications made will be done. .end literal .hl 4 REPLACE .literal FORMAT: REPLACE [qualifier] field-range WITH new-value DEFAULTS: If qualifier is not specified, /FLOAT is assumed. Replaces the specified fields in the record with the new-value. Valid qualifiers are /ASCII, /OCTAL, /BYTE, /WORD, /LONG, /FLOAT, /DOUBLE, and /HEX. The substitution string must be valid for the given mode of replacement (i.e. REPLACE/OCTAL 1:3 WITH 8 will result in an input conversion error). To prevent the upcasing of the substitution, enclose it in double (") quotation marks. Blanks are always ignored in numeric constants. Floating values that exceed the range defined for FORTRAN F and D values will also result in an input conversion error. A detailed explanation of the qualifiers follows: /ASCII The /ASCII switch tells FDMP to accept the substitution character for character. The replacement begins at the value specified in the field range, and its length is the length of the replacement. Spaces are allowed in the substitution. The substitution may be up to 255 characters in length. One byte is substituted for each character in the input string. /BYTE The /BYTE switch tells FDMP to accept the value as a signed byte. One byte is replaced for each replacement done in the record. /DOUBLE The /DOUBLE switch tells FDMP to accept the value as a double- precision floating point number. Eight bytes are replaced for each substitution. Floating values may in exponential format. /FLOAT The /FLOAT switch tells FDMP to accept the value as a single- precision floating point number. Four bytes are replaced for each substitution. Floating values may be in exponential format. /HEX The /HEX switch tells FDMP to accept the value as an unsigned hexadecimal constant. Four bytes are replaced for each substitution. /LONG The /LONG switch tells FDMP to accept the value as a signed I*4 constant. Four bytes are replaced for each substitution. /OCTAL The /OCTAL switch tells FDMP to accept the value as an unsigned octal byte. One byte is replaced for each substitution. /WORD The /WORD switch tells FDMP to accept the value as a signed I*2 constant. Two bytes are replaced for each substitution. .end literal .hl 4 VIEW .literal FORMAT: VIEW DEFAULTS: not applicable View simply displays the current data record as it has been edited this time. .end literal .hl 2 EXIT .literal FORMAT: EXIT DEFAULTS: not applicable Creates a new version of the data file if editing has been done. Note that EXIT does not leave FDMP. (The only way to leave FDMP is to use QUIT.) .end literal .hl 2 FULLSCR .literal FORMAT: FULLSCR ON FULLSCR OFF DEFAULTS: FULLSCR OFF Enables the 'full-screen' dump for VT100 family terminals. If the user is using a VT100 (or foreign terminal, set up as explained under the command CLEAR in this section), scrolling regions will be set up and the name of the file along with column headings will appear at the top of the terminal. This command will not work on other types of terminals, and an error message will be issued and FULLSCR turned OFF by FDMP if it is attempted on a non-VT100. The setting of FULLSCR has no affect on the format of the dump written to the disk file (assuming PRINT has been enabled). .end literal .hl 2 HELP .literal FORMAT: HELP [topic [subtopic1 [subtopic2...]]] DEFAULTS: If no topic is specified, the HELP on HELP will be displayed, along with available topics. The HELP command enables the user to get on-line documentation on the use of FDMP. The HELP command will give help, and if there is additional information available (sub-topics), will prompt the user for a sub-topic. To exit help, type a control-Z (CNTL-Z) after the prompt message, or when given the prompt "Topic?", just hit a carriage return (CR). .end literal .hl 2 LOGGING .literal FORMAT: LOGGING ON LOGGING OFF DEFAULTS: LOGGING OFF This command enables the user to save the commands he enters in a log file, which is called FDMP.LOG, which is put in the current working directory. .end literal .hl 2 OPEN .literal FORMAT: OPEN [/VARIABLE] DEFAULTS: If an extension is not provided with the file name, .DAT is used. This command opens a file for subsequent editing or dumping. Any valid VMS file specification may be entered (up to 63 characters maximum). This includes node specifications, although the program will not correctly handle these files (see limitations under the introduction for more information). Specifying VARIABLE tells FDMP to interpret the records in the data file as variable length records (versus segmented, which is the FORTRAN default). If VARIABLE is not specified, the records will be interpreted as segmented. .end literal .hl 2 PRINT .literal FORMAT: PRINT ON PRINT OFF DEFAULTS: PRINT OFF Enables or disables the sending the display of record contents to a disk file. FDMP will not print this file. The file is called DUMP.OUT and is placed in the current working directory. .end literal .hl 2 QUIT .literal FORMAT: QUIT DEFAULTS: not applicable Leaves the FDMP program. This is the ONLY way to leave FDMP. .end literal .hl 2 READ .literal FORMAT: READ DEFAULTS: if an extension is not provided, the program will add the extension .DAT. Reads in from an auxilary file commands to be performed by FDMP. When FDMP is through reading in commands, control will return to the terminal, and the fdmp> prompt will appear. The file specification is limited to 63 characters maximum. .end literal .hl 2 REMOVE .literal FORMAT: REMOVE MACRO REMOVE ALL DEFAULTS: none Removes a macro definition from the internal working tables of FDMP. Up to 20 macros may be defined at one time. If the macro name given matches more than one entry (i.e., macro name ABC matches macro names ABCDEF and ABC123), all matching entries are removed. REMOVE ALL removes all macro definitions. .end literal .hl 2 REVERSE .literal FORMAT: REVERSE ON REVERSE OFF DEFAULTS: REVERSE OFF Reverses the order (swaps) bytes that are read in the data record. When dumping numeric values, the results are only correct for I*2 (word) values. .end literal .hl 2 SEARCH .literal FORMAT: SEARCH [qualifier] [record-range] FOR value DEFAULTS: If qualifier is not specified, /ASCII is assumed. If record-range is not specified, the whole file is searched. Causes FDMP to search over the specified record range for a particular value. The record number and byte position are displayed for the first match in the record, and if DISPLAY is ON, the record is displayed also. Valid formats for record-range are m any single record m:n a range of records. n must be greater than or equal to m. Valid qualifiers are /ASCII, /OCTAL, /BYTE, /WORD, /LONG, /FLOAT, /DOUBLE, and /HEX. If a qualifier is not given, /ASCII is assumed. The search-string must be valid for the given mode of search (i.e. SEARCH/OCTAL 1:3 FOR 8 will result in an input conversion error). Blanks are always ignored in numeric constants. Floating values that exceed the range defined for FORTRAN F and D values will also result in an input conversion error. Note that matches must be EXACT; i.e., a double precision search must match all 8 bytes. ASCII searches for uppercase, unless the search-string is enclosed by double quotation (") marks. If record-range is not given, the whole file is searched. A detailed explanation of the qualifiers follows: /ASCII The /ASCII switch tells FDMP to accept the search-string character for character. Spaces are allowed in the substitution. The search string may be up to 255 characters in length. /BYTE The /BYTE switch tells FDMP to accept the value as a signed byte. /DOUBLE The /DOUBLE switch tells FDMP to accept the value as a double- precision floating point number. /FLOAT The /FLOAT switch tells FDMP to accept the value as a single- precision floating point number. /HEX The /HEX switch tells FDMP to accept the value as an unsigned hexadecimal constant. /LONG The /LONG switch tells FDMP to accept the value as a signed I*4 constant. /OCTAL The /OCTAL switch tells FDMP to accept the value as an unsigned octal byte. /WORD The /WORD switch tells FDMP to accept the value as a signed I*2 constant. .end literal .hl 2 SHOW .literal FORMAT: SHOW ALL SHOW CURRENT SHOW FILE SHOW FLAGS SHOW MACRO DEFAULTS: not applicable, except for SHOW MACRO, for which macro name has no default. Displays various information about the current state of FDMP. SHOW ALL shows all current macro definitions. SHOW CURRENT displays the current (default) macro definition. SHOW FILE displays the fully qualifed name of the current file. SHOW FLAGS displays various operating flags of FDMP, such as whether or not DISPLAY is ON. SHOW MACRO displays the macro definition associated with the given name. If the name matches more than one currently defined macro name, all matches are displayed. .end literal .hl 2 SUMMARY .literal FORMAT: SUMMARY ON SUMMARY OFF DEFAULTS: SUMMARY OFF Enables or disables the display of the length of each data record as it is dumped. .end literal .chapter Using FDMP .fill .ap .hl 1 Examining data files FDMP was written primarily for the examination of unformatted data files. It is imagined that this is how it would be used most often. The best way to learn how to examine data records is by trial and error. Use of FDMP assumes that the user knows what the data records in a file contain, or at least are supposed to contain. It is possible, of course, to dump a record in several different formats and compare them to see what is supposed to be "correct". There are several idiosyncracies of the program which the user should be aware of, since they can be a factor in program execution and speed. The first of these is that when dumping records, and the data record is greater than 32768 bytes, a call to get virtual memory will be issued; assuming that works correctly, the data record will be dumped as usual. After the record has been displayed, the virtual memory is released. (This get and release applies to SEARCH commands also.) If the call to get virtual memory fails, that record is skipped. This get and release of memory takes time, but ordinarily should not slow down program performance. The next "feature" of the program has to do with the SEARCH command. Since the VAX macro instruction MATCHC can only take a scan of up to 65535 characters, an extremely large data record will be split along 65535 byte boundries. If the search string overlaps this boundary, the search will fail. Also, SEARCH will only report the byte position of the first occurance of a match in any one data record. The last, possibly most restrictive limitation, of FDMP is the way it expands user-given macro definitions by which to dump data records. There is an internal buffer used to expand the macro definitions given it, and this buffer is limited to 65535 characters. If the user gives a macro definition of 4000L, 4000 bytes of this internal buffer will be used. Hopefully the buffer is large enough that it is larger than most data records would ever be. (It is sufficiently large for fixed-length records, as they are limited, at least under VMS version 3 to 32767 bytes.) Note also that even though a macro definition character (such as D or T) may take one byte of internal buffer storage, it will dump eight bytes out of the data record. The program will dump records on magnetic tape, so long as it is a labeled tape, or a foreign tape with fixed length records. When dumping from tape, however, the program issues a FORTRAN REWIND after each dump, so it may take a while for the tape to reposition itself. The user would be much better off copying the file to disk and then using FDMP. To dump from a foreign tape, mount the tape foreign with a blocksize and recordsize, and when FDMP is operating, just give the name of the tape drive for the OPEN command (e.g., OPEN MTA0:). On labeled tapes, after mounting, just give the file name, and the ACP should take care of the rest. When dumping records, a series of numbers will appear on the left side of the actual data contents. These numbers refer what are called the field entries in each record. For example, if FDMP put out a line like: .literal 1 - 5 000 -1278 0A897E00 AB .end literal Assuming the macro definition was OWH2A, the numbers reference the data record as field 1 being the octal byte, field 2 the signed word, field 3 the hex longword, and fields 4 and 5 both ascii characters. If the user does not know how many records a file contains, he should either turn the SUMMARY option ON, and then dump the whole file, noting that last record number to appear. If dumping the whole file is impractical, then he should dump giving a range of some record to a very large record number (e.g., DUMP 1:999999), and then note the record number of the last data record dumped, as mentioned previously. The concept of the current macro definition is used in the documentation on the commands. This refers to a previously used macro definition, used in either a DUMP or EDIT command. For example, if the user had two macros defined (named 1 and 2, of course), issuing the command DUMP USING 1 would dump the entire data file using macro definition 1 to define the format of the dumped records. Subsequent DUMP or EDIT commands issued without a USING parameter would use macro definition 1, as it is defined as the current macro definition. A DUMP or EDIT command given with the USING 2 parameter would replace the current macro definition with the definition for macro 2. The SHOW CURRENT command will show which macro definition is the current definition. When an error occurs dumping data records, FDMP will generally fail to report the contents of the data record. This usually means that a file is being dumped that FDMP cannot handle, such as an indexed file or a file with a record type of VARIABLE. FDMP will take other actions, according to several other types of non-fatal errors. If a value being dumped in floating point (either single or double precision) happens to be a reserved operand, FDMP will issue a diagnositic message, convert the floating value to zero, and continue dumping of the data record. If the macro definition is longer (in byte expansion) than the data record, the data record will be dumped using the first portion of the macro definition. For example, if a macro definition was 1000F, and the data record only contained 500 single-precision floating values, the first part of the macro definition would be used, giving 500 floating values. If the macro definition expansion is less than the data record, only that part of the data record that the definition covers will be dumped. FDMP will not repeat or expand the macro definition arbitrarily as to cover the "undefined" bytes remaining in the data record. One last thing to the user should be aware of is the difference between SEGMENTED records and VARIABLE records. A segmented record is a logical record, made up of one or more variable length records, each record containing (under VMS version 3) only the normal two-byte header defining the length of the variable length record, but another two-byte header directly following the variable length header which tells what kind of physical part this record is to the logical segmented record. Since the segmented record can contain an unlimited amount of these physical variable length records, there is no practical limit on the size of a segmented record. There are four such kinds of physical records: FIRST, NONE, LAST, and ONLY (these names are mine, but are self-explanatory). A FIRST header (currently an I*2 value of one) indicates that this physical record is the first in a series of variable length records comprising the logical segmented record. A LAST header (currently an I*2 value of two) indicates that this physical record is the last variable length record in the logical segmented record. A NONE header (currently an I*2 value of zero) indicates that this physical record is in the middle of a FIRST and LAST record. An ONLY header (currently an I*2 value of three) indicates that this physical record is the only variable length record in the logical segemented record. Since the logic for the splitting of segmented records into one or more special variable length records seems to be within the FORTRAN run-time library (also the reconstruction when these files are read back in by a user program), all of these actions taken by the system are transparent to the user. This point is brought up because if the user used the standard DUMP utility (which uses RMS $GET's) on his unformatted file with the /RECORDS switch, he would a dump of the special variable length records, but not the logical segmented records, since RMS knows nothing about files with a record type of segmented. FDMP, however, while also using RMS $GET's, has the logic built in to reconstruct the logical segmented record (which is what the user's program originally produced). .hl 1 Editing data files The editing capability of FDMP is somewhat limited, but can be useful in replacing a value here and there. It must be remembered that data files with records greater than 32768 bytes cannot be edited, at least not correctly. It is also not possible to edit a file which is on a tape mounted foreign. Records in a data file should be edited in sequential order, as again the program issues a FORTRAN REWIND after each EDIT command is completed. It should also be pointed out that editing a record a second time will not have a remembrance of what changes were made the first time. That is to say that if the user replaces a value, issues an EXIT command to save the new data record in the work file, and then comes back at a later time and edits that record, he will be editing the old record from scratch again. On top of this, FDMP, when creating a new file, will only include that last edit made on each edited record. See Example 2 in this chapter for more details on this. When editing a data file, FDMP will use 3 work files, which are called FDMPWORK1.DAT, FDMPWORK2.DAT, and FDMPWORK3.DAT. These files are automatically delete by FDMP, and should be sufficiently small so as to cause problems to the user who is having to contend with disk quotas. FDMPWORK1 contains a record for each time the user issues an EXIT command from the FDMP editor. This record contains the updated buffer contents, plus two house keeping values placed at the beginning of the record. FDMPWORK2 is FDMPWORK1 after having been sorted. FDMPWORK3 is FDMPWORK2 after stripping out of duplicate records (changes made to the same data record make duplicate entries in FDMPWORK2), as the user will remember as stated above that when creating a new file, FDMP will only include the last editing of that data record. FDMP then merges records from the old data file, plus new records from FDMPWORK3, and creates a new file. When editing, the individual entries in the data record are referenced by their field-number, as mentioned above in the section on examining data records. When doing editing, it is extremely important that the user understand each of the letters used in the macro definition and their length in terms of bytes. If a macro were defined to dump in data record in 100 octal bytes (100B), and the user issued a command REPLACE/DOUBLE 3 WITH 2., eight bytes, starting with byte three would be modified. The record will still be displayed all in octal, again. .hl 1 Examples The following examples will hopefully be an aid to the user in using FDMP examining and editing of data file records. Example 1 shows the use of DUMP and various interpretations of data records (signed, unsigned, etc.) Example 2 shows the use of EDIT, including replacement and deletion of elements in the data record, etc. Example 3 shows the use of SEARCH, and the EDITing of an executable image. .literal For examples 1 and 2, assume the data file being examined was produced by the following program (the usefulness, logic, or any other attribute of the following program cannot be accounted for). Example 3 will refer to the executable image itself. PARAMETER DEG_TO_RAD = 3.14159 / 180. CHARACTER*9 TODAY CHARACTER*8 NOW OPEN (UNIT=4, NAME='DRA0:[USER]TRIG.DAT', TYPE='NEW', 1 FORM = 'UNFORMATTED') CALL DATE(TODAY) CALL TIME(NOW) WRITE(4) TODAY, NOW DO I = -180, 180, 2 ANGLE = FLOAT(I) * DEG_TO_RAD SINE_OF_I = SIN(ANGLE) COSINE_OF_I = COS(ANGLE) TANGENT_OF_I = TAN(ANGLE) WRITE(4) I, SINE_OF_I, COSINE_OF_I, TANGENT_OF_I ENDDO END This program will produce an unformatted data file with a record type of SEGMENTED. In terms of segmented records, the file will contain 182 records, the first of which is 17 bytes long, and the rest 16 bytes long. Notes to all examples: 1) Comments for the examples will appear in square brackets. 2) All user input will appear in upper case letters. 3) The commands entered here will be spelled out in their entirety, although there is no reason for the user to do this, so long as the commands he enters have enough characters to be unambiguous. .end literal .hl 2 Example 1 .literal [The user invokes FDMP, and defines 3 macros by which to dump the data records. The prompt, "fdmp>", is issued by the system.] $RUN FDMP fdmp>DEFINE MACRO DATETIME 9A,8A fdmp>DEFINE MACRO SIGNED L,3F fdmp>DEFINE MACRO UNSIGNED UL,3F [The user now opens the data file, and dumps the header record using macro definition DATETIME.] fdmp>OPEN DRA0:[USER]TRIG.DAT fdmp>DUMP 1 USING DATETIME [FDMP now responds with the dump of the data records. The values 1 through 17 correspond to each of the 17 characters in the header. There is a blank preceding the 6 in the date, if there appears to be only 16 characters.] 1- 17 6-JUN-8311:58:38 [The user now decides he wishes to see only the record lengths of records 5:10, so he turns the SUMMARY option ON and turns OFF the display option.] fdmp>SUMMARY ON fdmp>DISPLAY OFF fdmp>DUMP 5:10 [FDMP now responds with the segmented record length in bytes] record # 5 is 16 bytes long. record # 6 is 16 bytes long. record # 7 is 16 bytes long. record # 8 is 16 bytes long. record # 9 is 16 bytes long. record # 10 is 16 bytes long. [The user now turns back on the display, turns off summary, and dumps records 2 through 10 using macro SIGNED to interpret the data values in the record.] fdmp>SUMMARY OFF fdmp>DISPLAY ON fdmp>DUMP 2:10 USING SIGNED [FDMP now dumps records 2 through 10 interpreting the 16 byte records as a signed longword followed by three single-precision floating values.] 1- 4 -180 -22.9676E-07 -10.0000E-01 22.9676E-07 1- 4 -178 -34.9018E-03 -99.9391E-02 34.9231E-03 1- 4 -176 -69.7588E-03 -99.7564E-02 69.9292E-03 1- 4 -174 -10.4531E-02 -99.4522E-02 10.5106E-02 1- 4 -172 -13.9175E-02 -99.0268E-02 14.0543E-02 1- 4 -170 -17.3650E-02 -98.4807E-02 17.6329E-02 1- 4 -168 -20.7914E-02 -97.8147E-02 21.2559E-02 1- 4 -166 -24.1924E-02 -97.0295E-02 24.9330E-02 1- 4 -164 -27.5639E-02 -96.1261E-02 28.6748E-02 fdmp>DUMP 2:10 USING UNSIGNED [FDMP now dumps records 2 through 10 interpreting the 16 byte records as an unsigned longword followed by three single-precision floating values.] 1- 4 4294967116 -22.9676E-07 -10.0000E-01 22.9676E-07 1- 4 4294967118 -34.9018E-03 -99.9391E-02 34.9231E-03 1- 4 4294967120 -69.7588E-03 -99.7564E-02 69.9292E-03 1- 4 4294967122 -10.4531E-02 -99.4522E-02 10.5106E-02 1- 4 4294967124 -13.9175E-02 -99.0268E-02 14.0543E-02 1- 4 4294967126 -17.3650E-02 -98.4807E-02 17.6329E-02 1- 4 4294967128 -20.7914E-02 -97.8147E-02 21.2559E-02 1- 4 4294967130 -24.1924E-02 -97.0295E-02 24.9330E-02 1- 4 4294967132 -27.5639E-02 -96.1261E-02 28.6748E-02 [The user is now tired of FDMP, so he quits and comes back tommorrow.] fdmp>QUIT .end literal .hl 2 Example 2 .literal [It is assumed that the user is working on the same file as before, and that he will use the same macro definitions. He has now decided that he does not want the time portion of the header record, and wants to change the value of the tangent of 90 degrees. It is also assumed that the data file is at version 1.] $RUN FDMP fdmp>DEFINE MACRO DATETIME 9A,8A fdmp>DEFINE MACRO SIGNED L,3F fdmp>DEFINE MACRO UNSIGNED UL,3F fdmp>OPEN DRA0:[USER]TRIG.DAT fdmp>DUMP 1 USING DATETIME [As before...] 1- 17 6-JUN-8311:58:38 fdmp>EDIT 1 [FDMP will now display the record as it was originally written, and then issue a different prompt, which is the record number followed by an ">". The user will now be in EDIT mode.] 1- 17 6-JUN-8311:58:38 [Since the time is in postions 10:17 as defined by the DATETIME macro, the user deletes these entries.] 1>DELETE 10:17 [FDMP now will redisplay the record with the updated values. Note that the field entries have changed, since there are now eight less characters in the data record.] 1- 9 6-JUN-83 [To save this change, the user must now enter an EXIT command, then to get out of editing he must use QUIT.] 1>EXIT 1>QUIT [Now the user will search for the record that contains the INTEGER*4 value for 90, giving him the data record with the value sine, cosine, and tangent of 90 degrees. In order to get the values to print out correctly, he must change the current default macro definition. This is done simply by dumping one record using the desired macro definition.] fdmp>DUMP 2 USING SIGNED 1- 4 -180 -22.9676E-07 -10.0000E-01 22.9676E-07 fdmp>SEARCH /LONG FOR 90 match in rec # 137 byte pos 1 1- 4 90 10.0000E-01 11.4838E-07 87.0791E+04 hit eof while searching [The user now edits record 137 with macro definition signed.] fdmp>EDIT 137 1- 4 90 10.0000E-01 11.4838E-07 87.0791E+04 [The user now replaces the value of the tangent field. Note that /FLOAT is assumed by REPLACE if none other is specified.] 137>REPLACE 4 WITH 1000000000. 1- 4 90 10.0000E-01 11.4838E-07 10.0000E+08 137>EXIT 137>QUIT [The user, now decides he still does not like the format of the header record. He will now change the date to the 7th of June, since he went home yesterday after initially creating the file. Note that he will have to start his editing of this record from scratch, since FDMP does not keep track of edited records.] fdmp>EDIT 1 USING DATETIME 1- 17 6-JUN-8311:58:38 1>REPLACE /ASCII 1 WITH "07-Jun-83" 1- 17 07-Jun-8311:58:38 1>DELETE 10:17 1- 9 07-Jun-83 1>EXIT 1>QUIT [The user is tired again, so he will exit FDMP to create his new file, quit to get out of FDMP.] fdmp>EXIT [FDMP takes his input, and creates a new version of the file being edited.] Created: DRA0:[USER]TRIG.DAT;2 182 record(s) fdmp>QUIT .end literal .hl 2 Example 3 .literal [The user does not trust FDMP, so he will now check out to see if his data file was actually modified the way he wanted. He also will have to have his files moved to a different disk, DRA1: (from disk DRA0:), although he still will have the same directory. He does not want to have to recompile his original program, so he will use FDMP on the executable image, since image files are 512 byte fixed-length record files.] $RUN FDMP fdmp>DEFINE MACRO DATETIME 9A,8A fdmp>DEFINE MACRO SIGNED L,3F fdmp>DEFINE MACRO UNSIGNED UL,3F fdmp>OPEN DRA0:[USER]TRIG.DAT;2 fdmp>DUMP 1 USING DATETIME 1- 9 07-Jun-83 [The user is suprised that it worked, but what should he have expected? He will now work on his executable image. He will clear out all of the old macro definitions, create a new one for the image file, and do a search for the compiled character constant "DRA0:[USER]TRIG.DAT". He will then replace the DRA0 with DRA1, create a new version of the image, and he will be all set to go on his new disk.] fdmp>REMOVE ALL fdmp>DEFINE MACRO IMAGE 512A fdmp>OPEN DRA0:[USER]PROGRAM.EXE [He now does the search. He needs to change the current macro definition, so he does a dump on first record of the image.] fdmp>DUMP 1 USING IMAGE 1- 50 ..0.@.L.....0204......................{.........h. 51- 100 ...........................PROGRAM.........01..... 101- 150 ............{....3A-16............................ 151- 200 .................................................. 201- 250 ..?.....$.......!............VMSRTL_001........... 251- 300 .................................................. 301- 350 .................................................. 351- 400 .................................................. 401- 450 .................................................. 451- 500 .................................................. 501- 512 ............ fdmp>SEARCH/ASCII FOR DRA0:[USER]TRIG.DAT match in rec # 2 byte pos 1 1- 50 DRA0:[USER]TRIG.DAT............................... 51- 100 .................................................. 101- 150 .................................................. 151- 200 .................................................. 201- 250 .................................................. 251- 300 .................................................. 301- 350 .................................................. 351- 400 .................................................. 401- 450 .................................................. 451- 500 .................................................. 501- 512 ............ hit eof while searching fdmp>EDIT 2 1- 50 DRA0:[USER]TRIG.DAT............................... 51- 100 .................................................. 101- 150 .................................................. 151- 200 .................................................. 201- 250 .................................................. 251- 300 .................................................. 301- 350 .................................................. 351- 400 .................................................. 401- 450 .................................................. 451- 500 .................................................. 501- 512 ............ 2>REPLACE/ASCII 1 WITH DRA1: 1- 50 DRA1:[USER]TRIG.DAT............................... 51- 100 .................................................. 101- 150 .................................................. 151- 200 .................................................. 201- 250 .................................................. 251- 300 .................................................. 301- 350 .................................................. 351- 400 .................................................. 401- 450 .................................................. 451- 500 .................................................. 501- 512 ............ 2>EXIT 2>QUIT fdmp>EXIT Created: DRA0:[USER]PROGRAM.EXE;2 3 record(s) [The user is now done, so he issues QUIT to leave FDMP.] fdmp>QUIT .end literal