SETFDATE -------- 2011-07-25 1. Overview ----------- SETFDATE is a privileged program that can change the creation date, modification date, access date, and modification time in a file label. SETFDATE runs on MPE V and MPE/iX. It can be used to update the date/time information for ordinary or privileged files. SETFDATE has a batch orientation, although it can be used programmatically. 2. Usage -------- SETFDATE can be run as a command, or as a batch oriented utility. SETFDATE takes a single command from its INFO string, executes it, and terminates. If INFO is empty, then SETFDATE will read a command from $STDINX, execute it, and loop to read more commands. This loop continues until a "//" is found or until an EOF (End Of File) is encountered. A control-Y will also terminate SETFDATE. The syntax for SETFDATE commands is: ! comment text : mpecommand [dash_options] file[.group[.acct]] [options] Where "options" is: [Cdate], [Mdate], [Adate], [Mtime], [AllocDate], [AllocTime] And "dash_options" are defined later. Comments may be included within any "file" command by enclosing them in either {...} (as in Pascal) or in <<...>> (as in SPL and SPLash!). The filename parameter must be provided. It may be in upper case, lower case, or mixed case. File equates are ignored. Lockwords are not required, and are ignored if provided. All other parameters are optional and are recognized by position. As an example, the following input would change the Adate: foo.pub.sys , , 1/1/91 Or, using comments to document what you are omitting: foo.pub.sys <>, {Mdate}, 1/1/91 Dates are in any of the following formats: Format Examples ------ -------- yymmdd 910627 dd mmmyy 23 Jan91 (TINDEX/TAPEDIR format) [m]m/[d]d/yy 06/27/91, 6/27/91, 7/4/91 TODAY (date at start of run of SETFDATE) NOFUTURE (if the old date is in the "future", then it will be changed to be TODAY) Times are in any of the following formats: Format Examples ------ -------- hh:mm:ss 12:49:00 hh:mm AM 10:34 AM hh:mm PM 10:34 PM NOW (time at start of run of SETFDATE) Any dates or times that are omitted are unchanged. (See the explanation of PARM bit 13 for one exception.) Example commands: editor.pub.sys 910627, 910627 (changes creation date and modification date only) Whenever any dates are specified, SETFDATE will ensure that the modification and access dates are reasonable relative to the creation date, and that the access date is reasonable relative to the modification date. The basic decision mechanism here is: - obtain old dates/times - apply any new dates/times to in-memory copy of dates/times - if creation date > modification date then modification date := creation date - if creation date > access date then access date := creation date - if modification date > access date then access date := modification date - if any dates/times have changed from old values, then post dates/times to file label Note: "date1 > date2" can be read as "date1 more recent than date2". As the above pseudo-code implies, if no dates/times are specified on a command line, the file label may still be updated to fix a date inconsistency. If this is not desired, then file names without dates/times should not be in the command input. 3. Options & help ----------------- If SETFDATE is run with an INFO string of "?", or if it is run with the HELP entrypoint (RUN SETFDATE, HELP), it will display help information and then terminate without processing any commands. SETFDATE displays an initial version & copyright statement of the form: SETFDATE 20080125 Copyright (c) 1991 Allegro Consultants, Inc. At present, the following PARM bits have been defined: Bit +value Meaning --- ------ ---------------------------------------------- 15 1 1 = verbose 0 = quiet (default) 14 2 1 = Show final dates/times for each file 0 = don't show the final dates/times (default) 13 4 1 = NOFUTURE assumed for any omitted dates 12 8 1 = Changes Only : suppress reporting information about a file if nothing was changed. 11 16 1 = Show Future : report file information for "future" date files, even if Show Dates was not requested. 10 32 1 = Report file information in batch format even if user is interactive. 9 64 1 = Don't prompt interactive users 8 128 1 = use first date (creation date) for all non-provided dates 7 256 1 = disable updating the file label on disc 6 512 1 = disable prohibition against TEMP files 3 %10000 1 = show cpu & elapsed time required to update a file 2 %20000 1 = debug dates \ 1 %40000 1 = debug flab > requires SM capability 0 %100000 1 = debug ufid / 2 %20000 1 = debug dates \ 1 %40000 1 = debug flab > requires SM capability 0 %100000 1 = debug ufid / Many of the above options can be specified as "dash_options" ... in the list below, the uppercase portion indicates the minimum length you must enter for the option to be recognized. If set, an option will persist until changed. -ALL_NOFUTURE -ALL_NOANCIENT -Changes_only -DEBUG_FLAB -DEBUG_dates -DEBUG_PARSE -DEBUG_UFID -DISABLE_TEMPCHK -DISABLE_WRITE -Show -SHOW_Dates -SHOW_Future, -SHOW_Times -USE_FIRST_ALL -Verbose -WANT_BATCH_LAYOUT -WANT_NO_PROMPT -YYmmdd dates are in yy-mm-dd format 4. Error Handling ----------------- If SETFDATE is run with an INFO parameter, any error will result in setting the JCW to a negative value. If no error occurs, JCW will be unchanged. The fact that JCW is left untouched when no errors occur means that multiple runs of SETFDATE can be done, followed by a single check of JCW (if desired). If MPE V (or MPE/iX) does not support a particular date or time field, SETFDATE will skip that one field and apply any valid dates/time updates. This skipping is not considered to be an error. If any date or time is invalid for a given command, an error message will be sent to $STDLIST and the command is skipped. This means that no partial updates will be done for the file. If an error occurs in a "batch" oriented run (where multiple commands are being read from $STDINX), SETFDATE will set JCW and continue reading and processing subsequent command lines. If an error occurred, the final value of JCW will represent the most recently occurring error. Dates with a year value of more than 1999 are not allowed. However, "future" dates are allowed. 5. Security ----------- Users with System Manager (SM) capability are allowed to change the dates/times of any file. Account managers (AM) and Account Librarians (AL) are allowed to change the dates/times of any files in their logon account. Group librarians (GL) are allowed to change the dates/times of any files in their logon group. Users with none of the above capabilities, will not be able to change the dates/times of any groups. Any attempts by unauthorized users to change a file date/time will be rejected with an error message, and SETFDATE will continue. (It continues because some files may still be accessible to the user.) 6. Implementation ----------------- SETFDATE will effect the date/time updates by calling FLABIO on MPE V, and FLABIO' on MPE/iX. Although these are undocumented procedures in the operating system, we believe that they will remain safe to use for the forseeable future. SETFDATE will function as follows: 1) parse the command (skipping the rest of the steps if an error occurs) 2) Call FLABELINFO to determine if the file exists, and to get the address of its file label (ldev & sector). If the file does not exist, skip the rest of the steps. On MPE/iX, the Unique File Identifier (ufid) is obtained instead of an ldev/sector combination. 3) [Obtain appropriate locks.] 4) Call FLABIO or FLABIO' to read the current file label contents. 5) Update the appropriate fields. 6) Call FLABIO or FLABIO' to write the new file label contents. 7) [Release locks.] Note: locking strategy to be determined. 7. Testing ---------- Two types of testing are to be done: destructive and test suite. 7.1 Destructive ---------------- Tester should try to "break" the software. 7.2 Test Suite ---------------- Test setup: 1) Tester must be logged on as a user with only IA capability. 2) The logon group must be other than "pub". 3) Local file "T" must exist. (BUILD T will suffice) 4) File T.PUB must exist. (BUILD T.PUB will suffice) 5) No file called NOTHERE.PUB.SYS should exist. Test is accomplished by running SETFDATE with the following input. Note: each line has a comment field that indicates the expected error number. If a different error (or no error) is generated, then the test has failed. t; ! 1 Expected a date t 910230 ! 2 invalid date t 13/3/91 ! 3 Month must be in range 1..12 t 3 ! 4 Expected "/dd/yy" t 3/ ! 5 Expected "dd/yy" t 3/32/91 ! 6 Day must be in range 1..31 t 1/1 ! 7 Expected "/yy" t 1/1/ ! 8 Expected "yy" t 1/1/70 ! 9 Year must be in range 71..99 t 2/30/91 ! 10 invalid date t today,,,z ! 11 Expected a time t ,,, 24:00 ! 12 Hour must be in range 0..23 t ,,, 23 ! 13 Expected ":mm" t ,,, 23: ! 14 Expected "mm" t ,,, 23:60 ! 15 Minutes must be in range 0..59 t ,,, 23:59:z ! 16 Expected "ss" t ,,, 23:59:60 ! 17 Seconds must be in range 0..59 t ,,, 23:23 am ! 18 AM Hour must be in range 1..12 t ,,, 23:23 pm ! 19 PM Hour must be in range 1..12 t ,,, 23:23 zm ! 20 Expected AM or PM t ,,, 11:23 am z ! 100 Unexpected trailing input t23456789 ! 101 Invalid file name nothere.pub.sys ! 102 File does not appear to exist t ,,,now ! 104 SM, AM, AL or GL capability is required t.pub ,,,now ! 105 SM, AM, or AL capability is required editor.pub.sys,,,now ! 106 SM capability is required The above test suite should generate all errors that SETFDATE is capable of generating except for two: 103 and 107. These two errors should not occur, as they reflect problems internal to MPE routines. SETFDATE 20140822 Copyright (c) 1991 Allegro Consultants, Inc.