Digitized by the Internet Archive in 2013 http://archive.org/details/peripheralinterc877wyli UIUCDCS-R-77-877 ~yyu^L4 { UILU-ENG 77 1730 PERIPHERAL INTERCHANGE PROGRAM (PIP) by Douglas J. Wylie May 1977 DEPARTMENT OF COMPUTER SCIENCE UNIVERSITY OF ILLINOIS AT URBANA-CHAMPAIGN URBANA, ILLINOIS PERIPHERAL INTERCHANGE PROGRAM (PIP) BY DOUGLAS JOSEPH WYLIE D. S. , UNIVERSITY OF ILLINOIS, 1971 THESIS Submitted in partial fulfillment of the requirements for the degree of Master of Science in Computer Science in the Graduate College of the University of Illinois at Urbana-Champaign, 1977 Urbana, Illinois This work was supported in part by the National Science Foundation, Grant No. NSF DCR 72-03740 A01. Ill TABLE CF CONTENTS Page CHAPTER 1 USER'S MANUAL 1 1.1 INTRODUCTION 1 1.2 COMMAND STRINGS S 1.1 SINGLF-FILE COMMANDS 8 1. U MULTIPLE- FT IE COMMANDS 8 1.5 ACTION SWITCHES 9 1.6 QUALIFYING SWITCHES 19 1.7 TRANSFER COMMANDS 27 CHAPTER 2 PROGRAMMER'S MANUAL 30 2.1 OVERV T EW OF PIP 30 2.2 DESCRIPTION OF PROCEDURES 38 2.3 MAINTAINING PIP ....77 BIBLIOGRAPHY 8^ CHAPTER 1 USER'S MANUAL 1. 1 INTRODUCTION PIP (Peripheral Interchange Program) is a program to maintain the fil<- structure of the PDP-11 Disk Operating System (DOS). PIP's functions operate on whole files, not records within the files. Somp of the functions of PIP include: Listing of directories for users Listing of information about devices File transfers Commands are passed to PIP by commands typed on the keyboard. All commands are terminated by pressing the RETURN key. 1.1.1 CALLING AND EXITING PIP is run 'inder the program I. To execute PIP use the following seguence of commands: .1 to which T will respond with: then type PIP (PETUPN) PIP will then respond with a number sign (tt). Whenever PIP prints a * it is ready to receive a command string, and after completing the command, PIP will print another *. There are two ways to exit from PIP. The first is through the /KI switch which will return control to T. The other method is to type CTRL/C, RETURN, KI which will return you to the DOS monitor. 1.1.2 PIP SWITCHES tfost of the functions performed by PIP are specified by switches in the corrmand strinq. Switches are of two types: action and qualify inq. A switch is composed of a slash (/) followed by one or two letters. See Tables 1.1 and 1.2 for a summary of PIP's 3w i tches. Call Name Description /AL A llocate /DE Delete /DI Directory /EN Enter Allocate a contiquous file Delete the file List the directory Enter the User Identification Code (NIC) in the Master File Directory (MFD) /FC Fastcopy Copy from DECtape to DECtape /FR Free List the number of free blocks and the size of the largest contiguous block Kill PIP and return to T Change the protection of the file Rename the file List number of files and number of blocks for each user entered in the MFD Unlock the User File Directory (UFD) to recover the file List directories for all users Withdraw user from the MFD Table 1.1 Action Switche: /KI Kill /PR Protect /RE R ename /UI User Information /UN Unlock /TD Total Directory /WD Withdraw Call Name Description /BE Before /BP Brief Directory /BT Between /CO Contiguou /E7 Except Operate on files created before specified date List abbreviated directory Operate on files created between two specified dates Contiguous Force output file to be contiguous Operate on files otherwise to be rejected /GT Greater than Operate on files with filenames lexicographically greater than specified filename /IN Inquire Ask for user confirmation before taking action /LK Length Operate on files on basis of file lengths /LT Linked Force output file to be linked /LT Less Than Operate on files with filenames lexicographically less than specified filename /PA Paginate Print directory with headings and in pages /PC Protection Operate on basis of protection code Code /SI Since Operate on files created since specified date /TY Type Operate on basis or file type /BP Update Update file, delete if file already exists /Z v Zero Zero the DECtape directory Table 1, 2 Qualifying Switches 1. 2 COMMAND STRINGS The commands processed by PIP are an extension of the DOS Command String Interpreter format. The general format of a command string is: DEVrFlLNAN. EXT[ u IC ]/S w 1 : v 1 : v 2 : . . . Vn/SW2:V1 : V2:. . . where each of the elements of the command string is explained be low. 1,2.1 DEVTCF SPECIFICATION The device specification, DEV: , is a string of from one to three letters optionally followed by an octal digit. The octal digit is the unit number of the device if the system has two or more of the specified devices. If the unit number is not specified, unit is assumed. If the device specification is not present, the system device is assumed.* *\n exception to this is the rename command (/HE) which in certain situations will assume a device other than the system device. See Section 1.5.9 for details. 1.2.2 FILENAME SPECIFICATION The filename specification, FILNAM, consists of a letter or $ optionally followed by from one to five radix-50 characters.* PIP also employs a star (*) convention which allows a filename to be incompletely specified. When a * appears in a filename specification, the command is referring to all files which have namps that match the filename up to the *. Thus: AB* refers to all files starting with AE * refers to all files. 1.2.3 FILENAME EXTENSION SPECIFICATION The filename extension specification, .EXT, consists of a period followed by from one to three radix-50 characters. As in the filename specification, the * convention may be used to incompletely specify the filename extension. •Valid radix-50 characters consist of the letters A-Z, the digits ")-9, and $. 1.2.4 IJSEP IDENTIFICATION CODS SPECIFICATION The user identification code specification, UIC, consists of a pair of octal numbers in the range of to 176 (octal), inclusive, separated by a comma and surrounded by square brackets. The first number refers to the group and the second the user within the group. In place of either the group or user specification, * may be used to specify all groups or users. Thus: [1,*1 refers to all users in group 1 j"*,200] refers to all users with user number 2C0 [*,*■) refers to all users in all groups An alternate way to specify a UIC is through predefined users. In the system file SYSHDE.STF is a list of mnemonic UIC's, Thus to specify the system user ([1,1 ]) it is only necessary to type: fSYS], In the absence of an UIC speci tica t ion, the UIC of the user currently logged in on the system is assumed. 1.2.5 SWITCH SPECIFICATION The switch specification, /SW:..., consists of a slash followed by one or two letters, and optionally followed by one or more value specifiers, each of which consists of a colon (:) followed by * string of one of more alphanumerics. 1.3 SINGLF-FILE COMMANDS Several of the PIP commands only require one file specification. For example: IDTO: ABC/DE will delete the file named ABC from the DECtape mounted on unit 0. These commands are distinguished by the absence of a '<' (or ,=, )» Sinqle-file commands may consist of two or more . file specifications in which case the action is performed on all files specified. For example: #FIL. 1,FIL.2/AL: 10 will create two contiguous files of length 10 (decimal) blocks. 1.U MULTIPLE-FILE COMMANDS Many of the PIP commands require both a source and a destination file specification. For example: #DT:FILE. NEW the file will be deleted. 2. If the user responds with 'A 1 the whole command will be aborted. 3. If the user responds with anything other than • Y' or 'A', the file will not be deleted but PIP will continue lookinq for files with extension COD. Commands ^hat normally require the presence ot a filename in the input dataset specifier may omit the filename if /IN is used, in which case the tilename and extension *. * is assumed (i.e., all files) . 27 1 . 6. 3. 2 Except The except switch, /EX, is used to specify that the action is to be performed on all files that otherwise would be rejected. For example: #*.COD/DI/EX will cause the listing of all files that do not have an extension of COD. When used in conjunction with other qualifying switches, /£X reters to all files which fail to meet any of the requirements, not only to files which fail to meet all of the requirements. Thus: #/ DT/FE:. TUN/ST: A UG/EX will cause the directory consisting of all files created before June 1 or after August 1 of the current year. Note that it does not cause the listing of the directory of all files created before June and after August. 1.7 TRANSFER COMMANDS In the absence of an action switch, PIP assumes that the function to be performed is a tile transfer. Transfers may be between ci le-struct ured or nonfile- structured devices. Transfer commands are of two types: either transferring and combining, or transferring without combining. 28 1.7.1 TPANSFEPRING AND COMRINING Several files may be concatenated together to form a single new file. This is done by specifying a filename in the output dataset specifier. For example: *FILE. EXT = DT1:FILE. 1, FILE. 2 will combine the files FTLE.1 and FILE. 2 on the DECtape mounted on unit one to form the file FILE. EXT on the system device. The resultant file is always linked if two or more files are specified by the input dataset specif ier (s) , regardless of the file types of the input files. The contiguous switch, /CO, is ignored. Thus: #FILE.NFW/CO=DT:FILE. 1, FILE. 2 #FITE. NEW=DT: FILE.* ♦FILE. NEW=DT: FILE. EXT/GT will all result in FILE.NFW being linked since in each of the above cases the possibility exists that two or more files may be combined. If there is only one input file specified, file type will be preserved. For example: ♦ FIL. N5W=DT:FIL.0LD will result in FIL.NEV being contiguous if and only if FIL.OLD was contiguous. If it is desired to create a single contiguous file from two or more files, the following procedure is recommended : *FTL. TMP=FIL.T,FIL. 2, FIL. 3 ♦ FIL. NEW/CO=FTL.THP ♦ FIL. TMP/DE 29 1.7.2 TRANSFERRING WITHOUT COMBINING When a filename is not present in the output dataset specifier,* all the files specified by the input dataset specif ier (s) are transferred as separate files. When transfers are between directory-structured devices, the file types are preserved in the absence of the link (/LI) or contiguous (/CO) switches. For example: #D T1 :=FIL.1, *.COD will transfer FIL.1 and all files with extension COD from the system device to the DECtape mounted on unit 1, preserving th^ir file types. *The limited * convention may be used in transferring without combining. For example: * AFILF. *=BFILE.* will transfer all files with a filename of BFILE and change the filename to AFILE. T he expanded * convention may not be used, thus: is illegal. 30 CHAPTER 2 PROGRAMMERS MANUAL The following sections deal with the algorithms in the program and how to maintain and update PIP. 2. 1 OVERVIEW OF PIP The organization of PIP is broken into three major parts. The first part is data structures used to implement the various commands. The second component is the procedures used to interpret the commands, and the third consists of the procedures used to execute the commands. 2.1.1 DATA STRUCTURES Ihe data structures in PIP are used to represent datasets, files, and UIC's. In addition, PIP utilizes several tables to facilitate the interpretation and execution of commands. 31 2.1.1.1 Representation of Datasets Datasets are represented by the type DATAS2TTYPE which is declared as record DVC, UNIT, UIC, N A HELEN, EXTLEN: inteqer; DVCSPEC: Boolean; NAMESPEC = (UNIQUE, NONUNIQUE, UNSPFC) end ; where DVC is the radix-5C encoding ot the device name UNIT is the unit number ot the device UIC is the specified user code (see Section 2. 2.1.3) NAMELEN is the number of characters present in the filename specification. EXTLEN is the same as NAMELEN except it is for the filename extension DVCSPEC is True if and only if the device was explicitly included in the dataset specifier NAMFSPFC tells how the filename and extension were specified : UNIQUE implies name explicity specified NONUNIQUE implies a * was found UNSPEC implies tilename not present. 32 2.1*1.2 Representation of Files In order to implement all of the features of PIP, in particular the expanded * convention and the additional qualifying switches, the information about files is considered to be composed of six fields. These fields are: 1. Filename 2. Filename extension 3. Lenqth of file U. File type 5. Creation date 6. Protection code When a file specification is input, the information in the dataset specifier is stored in two arrays, LOBND and UPBND which contain the minimum and maximum values respectively, for each of the above fields.* Similarly, each file in the user's UFD has its fields stored in the global array DATA. Thus, at all times, the file currently being accessed has the information about its fields available to all procedures. 2.1.1.3 FFPPESENTATION OF UIC'S PIP permits a * to be substituted for either the group or user ♦output files are uniguely determined so a range of values for the fields is not needed, rather a single value is sufficient to specify the output file. 33 nurrber in the UIC. The UIC is stored in one word: OUTDATASET.UIC for the output dataset and INDATASET. UIC for the input dataset. To determine if a given UIC matches the UIC specifier, PIP uses the global variable MASK to mask out either the group, the user, or both. The procedure DATASETSPFC initializes MASK and DATASET. UIC according to Table 2.1. GROUP USER MASK UIC speci fied speci fied unspeci Cied unspecified specified -1 256*group ♦ user unspecified 255 256*group specified -2 56 user unspecified Table 2. 1 Representation of UIC Then, a given user code (USER) is acceptable iff: USER S MASK = UIC The glohal variable USER contains the UIC of the user whose files acp currently being accessed. 3U 2. 1. 1. U TABLES PIP uses a number of tables to determine information about the qiven command. These tables are initialized by the procedure INITIALIZE. INITIALIZE inputs the values for the tables from the filo PIP, PIN which is found in UIC [1,1]. If the file PIP. BIN does not exist, the external procedure INIT is called to create the file. A list of the tables used and their functions is found in Table 2. 2. 35 Name Index Set Function BREAKCHAR char Boolean array, BB EAKCHAR[ ch ] is True iff ch is a break character (See Section 2, 2. 1, 10) DAYS 0..12 Integer array, DAYSf i ] is the day of the year of the last day of the ith month DE^AULTORDER P • . 6 Integer array used to determine the default ordering for the listing of directories LETTER char Boolean array, LETTER[ch] is True iff ch is a letter or dollar sign ($) ttULTICHAR switches Boolean array, NULTICHA R[ sw ] is True iff the switch sw needs to be specified with two characters. OWNEPCMD switches Boolean array, MULTICHA?[ sw ] is True iff the switch sw indicates a command that is restricted to the owner of the file. RAD5T 0.. 2, char Integer array used to convert from ASCII to radix-50. PAD50[i,ch] is the radix-50 value for the character ch when it occurs in the ith position. RAD50[i,ch] is -1 if ch is not a valid radix-50 character. SWITCHNAME switches Character array, S HITCH?1AME[ sw ] is the ASCII representation of the switch sw. UNPAD C..39 Character array, UNRAD[ i ] is the ASCII character that in radix-50 is represented as i. USPHUSTBETHFEE switches Boolean array, USR!1USTBETHERE[ sw ] is True iff tor the command determined by the switch sw, the current user must be entered onto the specified device. Table 2. 2 Tables Used by PIP 36 2. 1. 2 DB.SIC FLOW OF PTP The interpretation and execution of commands is broken into four parts. T, Determininq type of command 2. Fxtractinq the output data set specifier 3. Checkinq for syntax errors in the input, dataset specifier (s) U. Fxtractinq input dataset specifiers and executing the command for each input specifier. 2.1.2.1 Determination of Type of Command The typp of command is determined by scanning the command string and picking up action switches and any associated value specifiers. In the absence of any action switch, PTP assumes the command will be a file transfer. At the same time, it is determined whether the command is single-file or multi-file (denoted by the absence or presence of ' = • or • <*in the command). 2.1.2.2 Extracting Output Dataset Specifier If the scan determined that an output specifier was present, the dataset specifier is extracted from the command, and the file variables FILSOHT and DINARYFILE2 are assigned to the 37 corresponding fields of the dataset specifier. If no output specifier is present, the keyboard is assumed. 2,1.2.1 Checking for Syntax Errors Before any action is taken, the rest of the command is checked to ensure that there are no syntax errors. If a syntax error exists, the command is aborted. 2.1.2.4 Executing Command After it has been determined that the command is syntactically correct, each of the input dataset specifiers is aqain extracted from the command and the file variable INFILE is assigned to reflect the specified file. Then the actual execution of the command is begun. Section 2,2 describes the procedures used to effect the requested commands. 38 2.2 DESCRIPTION OF PROCEDURES As stated earlier, the execution of a command is broken into several parts. The following procedures deal with either interpreting a command or executing a command. The procedures used for determining the syntax of the command are found in Table 2. ? and the procedures used for the execution of the command are listed in Table 2.U. PROCEDURE DESCRIPTION DATASETSPEC Extracts a dataset specifier from the command DECIMAL Converts ASCII string to decimal number ENCODE Encodes three ASCII characters into their radix-50 representation FIFLD Determines field value specifier FINDCOLON Checks to see if current switch has an associated value specifier .jETMONTN Extracts a month and returns the day of the year of the first day of the month GETNEXTITEM Extracts the next item from the command string JULIAN Converts an ASCII date to its modified Julian representation 0C""AL Converts an ASCII string to an octal number OCTALOPST.ap Checks the command string for either an octal number or a star (*) SWITCH Determines the type of switch SYNTAXEPFOR Outputs an error message Table 2. 3 Syntax Procedures 3 9 PROCEDURE DESCRIPTION ALLOC ^NOTHFP AN07HERFILE ASSIGN ASCIITR^NSFER BINARYTR ANSWER DELETECMD DIREC^ORYCMD ENTEROIC ERROR FASTCOPY EINDUSER FREEBLKS HEADING LESSTHAN LI STFNTRY LISTFILEWAME LISTFILESANDBLKS PRTtfTDVCTJAM F REUAMECMD RFSPONSE SOFTDIRECTORY STAT TRANSFERCMD UNDIV UNMOD UNMPY UNPACK UNPACKDUTE VALIDFILE WHOL EDI RECTORY ZFROIT Performs the DOS allocate function Searches a directory for the next entry Returns the next file matching the current specif i cat ions Associates a file variable with the specified file Transfers an ASCII file Transfers a binary file Performs the delete file function Used for the listing of directory information Enters the UIC of the current user into the MFD of the specified device Outputs an error rressaqe and terminates command Copies from one DECtape to another Returns with the next user matching the current specifications Calculates the number of free blocks on the specified device Outputs headings for directories Performs an unsigned comparison Outputs directory information about a file Outputs a filename Outputs the number of files and blocks Outputs device name Performs the rename function Temporarily halts execution of command to seek user confirmation Sorts and outputs the directory for one user Returns the status of a device Transfers a file Performs an unsigned division Performs an unsigned modulus function Performs an unsigned multiplication Converts an integer from radix-5C to ASCII Converts a modified Julian date to DD-MMM-YY Checks to see if specified filename already exists Sorts and outputs directories for all users on a specified device Zeroes DECtapes TaDle 2. U Execution Procedures uo 2.2,1 SYNTAX PROCEDURES 2. 2. 1, 1 DATASETSETSPFC declaration: procedure DATASETSPEC (var DATASET: DATASETYPE) ; parameter: DATA SET dataset to be initialized description: DATASETSPEC extracts the next dataset specifier from the command, sets the fields of DATASET to reflect the specifier, picks up any associated qualifyinq switches, and returns the attributes of the specified device in the qlobal array ATTPIBUTFS.* A dataset specifier consists of four parts, any of which may be null: 1. Device specification 2. Filename specification 3. User identification specification U. Switch list The device specification, if present, is converted from ASCII to radix-SO. The encoded device name is assigned to DATASET. DVC. If a unit is specified., DATASET.. UNIT is set to the specified octal digit, otherwise, DATASET, UNIT is set to zero. ♦See Figure 2.1 for an abbreviated description of DATASETSPEC. U1 beg in if FNDCHAR = • : • then bpgin end ; if ENDTNDEX \= then beg in if ENDCHAR \= eol then begin end end ; i f KSIJCHAP = T ' then beg in end ; while ENDCHAR = •/' do begin if then begin end else end ; end ; Figure 2. 1 Outline of DATASETSPEC U2 2.2.1.1.2 Filename Specification If there is a filename specification present, the following action is taken: 1. The first three characters of its name are encoded into radix-50.* 2. If there are more than three characters, the second three are also encoded. (Any characters in excess of six are ignored) . 3. If there is a filename extension in the dataset specifier, (indicated by a '.' immediately following the filename specifier) the first three characters of the extension are encoded into radix-50. 2.2.1.1.3 User Identification Specification As explained in Section 2.1.1.3, the user identification specification may be of several forms. The global variable MASK and the QIC field of the parameter DATASET are assigned values according to Table 2.1. An alternate way of specifying the UIC is through the use of pre-defined user names. If the user identification specification is not of the form [ , ], the characters between the brackets are encoded into radix-50. Then the array TJS?>IflME is examined to see if a pre-defined user name has been established. If it has, DATASET. UIC is set to the correspondinq user code and MASK is set to -1. If no user name * q ee Section 2.2.1.2 for details U3 is found that matches the specified name, the command is terminated with an error message. 2. 2. 1. 1. U Switch List The dataset specifier may be optionally followed by a list of switches. If it is, for each switch present, the following action is taken: 1. Determine the type of the switch.* 2. Tf it is a qualifying switch,** the action specified in Table 2.5 is performed. 3. If the switch is an action switch, the value specifiers associated with the switch are skipped. *This is done with a call to SWITCH (Section 2.2.1.11). **7he action switches /TD, and /UI, both assume a user identification code specifier of [*.*], so DSTASETSPEC sets MASK to -1 and INDATASETUIC to to reflect this. ua SWITCH ACTION TAKEN BE Set upper bound for creation date to specified Julian date BP Get all fields to be listed for directory BT Set upper and lower bounds for creation dates to specifed Julian dates CO Set contiguous flag EX Set except flag GT Set upper bounds for filename and fi lename- extension to -1. Note that -1 equals 65535/ i.e., the largest possible number. IN Set the inquire flag LE Set the upper and lower bounds for the file length to the two specified values LI Set the link flag LT Set lower bounds for filename and filename extension to . 0. PA Set the paginate flag and determine lines per page PC Set the upper and lower bounds for the protection codes to the two specified values SI Set the lower bound for the creation date to the specified Julian date TY Set the upper and lower bounds for file type so that only linked or only contiguous files will be considered UP Set the update flag Z E Set the zero flag and get DECtape number Table 2.5 Actions Performed in Response to Qualifying Switches 45 2.2.1.2 ENCODE declaration: procedure ENCODE (INDEX, K: integer); parameters: INDEX index into ITEM of where encoding is to beqin K field to be set: implies first word of filename 1 implies second word of filename 2 implies filename extension description: ENCODE converts the string of characters in ITEM pointed to hy INDEX into a radix-5D packed word. The radix-50 value is stored in the array LOBND. It also sets the corresponding entry in UPBND appropriately, and the NAMESPEC field of DATA3ET is set to NONUNIQUE if a * is found in the ASCII string along with either the NAMELEN or FXTLEN field. 2. 2. 1. 3 DECIMAL declaration: function DECIMAL: integer; description: DECIMAL returns the unsigned value of the ASCII string in IT P M. U6 2. 2.1. U OCTAL declaration: function OCTAL (INDEX: integer); parameter: INDEX index into ITEM array of where conversion is to beqin description: OCTAL converts the ASCII strinq pointed to be INDEX in the array ITEM to an octal number. 2. 2. 1. 5 OCTALCRSTAP declaration: function OCTALORSTAR : inteqer; description: OCTALORSTAR is used to input either the qroup number or user number of a UIC, It extracts the next item from the command and returns -1 it the first character of ths item was a *. Otherwise OCTAL is called to qet the value. 2.2.1.6 JULIAN declaration: function JULIAN: inteqer; description: JULIAN is called when PIP is expectinq a date specifier. This may be from either the /BY., /SI, or /P' U7 switches. PIP allows six types of dates: DD-MMM-YY DD = day of month r HKH = first three characters of month, YY - year DH-mmm YY = current year assumed M^IM-YY DD = 1 assumed MMM DD = 1, YY = current year assumed YY DD = 1 , MHH = JAN assumed * current date assumed 2. 2. 1. 7 GVTMCNTH declaration: function GETMONTH: integer; description: GETMONTH returns the day of the year of the first day of the month in the array ITEM* 2. 2. 1. « FIELD declaration: function FIELD: integer; *a null date is valid only for /SI and /BE and is indicated by the absence of a colon after the switch. U8 description: FIELD extracts the next itPin from the command and checks the first character of the item. It returns a value according to Table 2,6. "irst Character Value Peturned* N V 2 C 3 L a T 5 P 6 U Table 2.6 Fie Id Specifiers Field Specified Filename Filename extension Creation date Length File type Protection code Unsorted** FIFLD is used tor two purposes, either to determine orderings for the listing of directories or to determine the fields to be listed in response to the /BR switch. 2. 2. 1. ? FINDCCLCN declaration: function FINDCOLON (SHOULDLSTHERE: Boolean) Boolean; ♦The value returned is the index into the array DATA of the field. ♦f^he value specifier U also sets the global variable SOPT to False. U9 parameter: SHOULDBFTHEPE True if the switch requires a value specifier description: FINDCOLON checks to see if the current item of the command was terminated by a ':'♦ If so, the next item of the command string is extracted and FINDCOLON returns True. If it was not terminated by a •:', SHOULDEETHERE is checked and if SHOULDBFTHEPE is True, FINDCOLON terminates the command with an error message. If SHOULDBETHER E is False, FINDCOLON returns False. 2.2,1.1° GFTNFXTIT5M declaration: procedure GETNEXTITEM; description: GETNEXTITEM extracts the next item from the command and stores it in the array ITEM. £n item is defined as any (possibly null) string of alphanumerics terminated by one of: : . , - = < r 1 eol In addition to returning the item, the following globals are also set by GETNEXTITEM: FIRSTCHAR First character of item EHDCHAR Character that terminated item ENDINDEX Number of characters in item POSITION Array the contains the position in the command of each character in the item 50 2.2.1.11 SWITCH declaration: function SWITCH: SWITCHTYPE; description: SWITCH extracts the next item from the command and then checks to see if it matches any of the switches in the array SWITCHNAME. If a match is found, SWITCH returns the cor responding switch. If no match is found, an error message is printed and the command is aborted. 2. 2. 1. 12 SYNTAXEEROR declaration: procedure SYNTAXEKHOR (MESSAGE: text; INDEX: integer) ; parameters: MESSAGE Error message to be printed on keyboard INDEX Index into ITEM of offending character description: SYNTAX2FB0H outputs the error message under the character where PIP got confused. The command is then aborted. 51 2.2.2 FXECUTION PROCEDURES 2.2.2.1 ENTERUIC dec] arat ion procedure ENTERUIC; description: ENTERUIC enters the UIC of the user currently Logqed in on the system into the MFD for the device on which the file TNFILS resides.* First the first MFD block is read into the array MFD, then the second MFD block is input and ENTFRUIC looks for an empty entry (one whose UIC is zero). If such an entry is found, the UIC of the current user is inserted into this position. The pointer to the UFD block is then cleared** and the MFD block is rewritten onto the device. Currently, PIP will not attempt to extend the MFD, so if ther° are no free entries, an error messaqe is printed. ♦Although ENTERUIC is normally called in response to the /EN switch, it may also be invoked (after user confirmation) when the UIC specified in the output specifier is not found in the MFD for the device. **If the device is a DECtape, the UFD pointer is not cleared, rather it is set to 102 (octal) since 102 is the start address for all UFD's of a DECtape. 52 2. 2, 2. 2 TFANSFERCMD declaration: procedure TRANSFFRG1 D; description: TPANSFEPCUD transfers the files specifed by the current input dataset specfier to the current output specifier. For each file that matches the current specifications TRANSFER either performs an ASCII or binary transfer. A binary transfer is used it both input and output devices support binary, otherwise the file is transferred as an ASCII file. 2.2.2.1 A SCI I TRANSFER declaration: procedure ASCIITRANSFER ; description: ASCIITRANSFER transfers an ASCII file from the current inout device to the current output device. The transfer is done one character at a time. 2.2.2.U BINAPyTPANSFER declaration: procedure BIN ARYTRANSFER ; 53 description: BINA RYTPANSFEF transfers a file from a device that supports binary input to a device that supports binary output. As such, it handles all transfers between file-structure devices. Since PIT endeavors to preserve file type when transferring files and since there are two types of transfer commands (transfer with combining and transfer without combining), BINAR YTR ANSFER must do the following if the output device is file-structured: 1. Tf the transfer is to be without combining (OUTDATASET. NAKFSPEC \= UNIQUE) then reassign the output file (forcing a close on the previous file) . 2. Check to see that there is not already a file in the UFD with the same filename and extension. (See Section 2.2.2.15 for details). Then, (whether transfering with or without combining) if the input tile was contiguous, or the contiguous flag (C0NTI3) is True, allocate contiguous space for the output file (unless the linked flag (LINK) is True.* After the file has been allocated (if reguired) then the file transfer is done. The actual transfer itself is done differently for linked and contiguous ♦The link flag may be set explicitly by the user with the /LI switch, or PIP may determine that the transfer must be linked. PIP forces the file to be linked if: 1. The input device is non-file structured; 2. ^ore than one input, data set specifier is present, or ; 3. \ * was used in the specification of the input data set filename. 54 files. If the input, is contiguous then the file must be transferred in 256 word blocks, whereas, if the file is linked, the transfer roust be in blocks of 255 words.* 2.2.2.5 DIPECTOFYCOtfMAND declaration: procedure DIRECTORYCOMMAND description: DIFECTOFYCOMMAND implements the /TD, /DI, and /UI functions. Depending on the command and whether or not the sort flaq is set (SORT) , a decision is made as to the action to be performed. If the command is UI, then WHOLEDIR ECTORY is called. Otherwise: if SOPT then if CMD = TD then WHOLEDIR ECTORY else repeat SOPTDIRECTORY until \FINDUSER else repeat while ANOTHERFILE do LISTENTPY until \FINDUSER *Due to peculiarities in DOS, the last block in a linked file cannot be transferred as 255 words. Instead, it must be transferred as 254 words plus one byte. 55 2.2.2.6 WHOLEDIBECTOBY declaration: procedure WHOLEDIRECTORY ; description: fc" HOLED IF ECTOR Y sorts the users found on the input device and then does one of two things: 1. If the command is TD, SOBTDI PECTOF Y is called to output the directory for each user. 2. If the command is UI, the UIC's and number of files and number of blocks in the user's UFD is listed. 2.2.2.7 SORTDIRECTOPY declaration: procedure SORTDIRECTORY descriotion: SORTDIRFCTOFY sorts and outputs the directory for a sinqle user, A doubly-linked list insertion sort is used. 56 2.2.2.8 LI ST ENTRY declaration: procedure LISTENTRY; description: LISTENTRY outputs the directory entry for the file whose fields are stored in the global array DMA. If the paginate flaq (PAGINATE) is set, LISTENTRY outputs a formfeed and prints headings when the end of a page is reached. The global array LIST is inspected to see which fields of the entry are to be output. 2.2.2.9 LISTFILESANDBLKS declaration: procedure LI5TFILESANDBLKS ; description: LISTFILESANDBLKS is called by the various directory procedures to output the number of files and blocks found. If the output device is the keyboard and no tiles were found, then the output is suppressed. 5 7 2.2.2.1^ PFTNTDVCNAHE description: PFINTDVCNAME outputs the device name of the current input device (INDATASET. DVC) , along with its unit number. If the device is a DECtape, then instead of the unit number of the device, the number of the DECtape is output (unless the DECtape is not numbered) . 2.2.2.11 PRINTIT declaration: procedure PRINTIT (name: text; VAL: integer) ; parameters: II A ME identifier to be output VAL value to be output description: PPINTIT outputs VAL followed by its description and optionally followed by an 'S 1 (the »S' is printed if VAL \= 1) 2.2.2.12 PRINTUIC declaration: procedure PRINTUIC; description: PPINTUIC outputs the UIC of the current user. 2.2.2.1? HEADING declaration: procedure HEADING; description: HEADING is called to print the headings for the listing of directories. 2. 2. 2, 1U FREFBLKS declaration: procedure FFEEBLKS; description: FREEDLKS checks the bit maps for the input device and outputs the number of free blocks and the largest group of contiguous blocks on the device. Prior to being called, the array M?D must contain the first MFD block for the device. 59 2. 2.2.1 ANOTHER declaration: function ANOTHER (var DIRECTORY: array [0..255] of intecjer; INCREMENT, MAXINDEX: integer; var ADDR, INDEX: integer; var CHANGED; Boolean) Boolean; parameters: DIRECTORY ADDR INDEX INCREMENT MAXINDEX CHANGED Directory to be searched Device address of current directory block Index into directory of where search is to begin Number of words per entry Index of last entry in block True if current directory block has been modified. description: ANOTHER searches through DIPECTORY looking for a non-zero entry. The search begins at INDEX into the current directory block. If such an entry is found, ANOTHER returns True and INDEX points to the next entry after the entry found. ANOTHER is used to search either a MFD or UFD. If the end of the current directory block is reached before a non-zero entry is found, ANOTHER does the following: 1. If CHANGED is True, the current directory block is rewritten to the device. 2. If there is another block associated with the directory (its link word is not zero), the next directory block is input, INDEX is set to 1 , ADDR is set to the address of the next block, and the search continues. 3. If there is not another block associated with the directory (its link word is zero), then ANOTHER returns False. 60 2. 2.2. 16 ANOTHEPFILE declaration: function ANOTHERFILE: Boolean; description: ANOTHERFILE checks to see it there is another file in the current user's UFD that matches the current input dataset specifier. If such a file is found, the following qlobals are assigned : N1 N2 ■PVT DATA First word of filename Second word of filename Filename extension Array that contains the values of each of the fields of the file. ANOTHEPFILE calls ANOTHER to get the next non-zero entry of the UFD and then checks to see if all of its fields fall within the ranges of the current input dataset specifier. (The arrays LOPND and UPDND contain the minimum and maximum values, respectively, for each of the fields.) After it has been determined whether or not the file is in range, the except flag (EXCEPT) is checked. If EXCEPT is True, then the file is in rang* 3 if and only it it falls outside of at least one of the fi°lds. If, at this point, thf» file is found to be acceptable, the inquire flag (INQUIRE) is checked. If it is True, then user confirmation is solicited before accepting the file. This process is continued until either a file is found that is acceptable (in which case ANOTHERFILE returns True) or there are no more files in the user's UFD (ANOTHERFILE returns False). 61 2. 2. 2. 17 FINDUSEF declaration: function FINDUSER: Boolean; description: FINDUSER checks the MFD for the current input device* and returns True if a UIC is found which matches the UIC specifier. The procedure DATASETSPEC (see Section 2.2.1.1) constructs a mask (MASK) to applied to all UIC's to determine if they match the input dataset specifier. FINDUSER also sets the qlobal USER to the UIC for the user if a user is found with the required attributes. 2. 2. 2. 18 RESPONSE declaration: function RESPONSE: Boolean; description: RESPONSE is used to seek user confirmation before ♦FINDUSER is also used to determine if the UIC of the output dataset specifier is on the output device. 62 continuinq the execution of a command. If the user types ' Y* , RESPONSE returns True. If the user types 'A* , the whole command is aborted. Any other response causes RESPONSE to return False. 2,2.2.19 STAT declaration: procedure STAT (FIL: file of character; var DVCNAKE: inteqer) ; parameters: FIL File whose device status is to be determined DVCNAME Standard device name of device description: STAT returns the characteristics of the device on which the file FIL resides in the global array ATTRIBUTES. The parameter DVCNAME is also set to the standard device name for the device (in radix-50) . Table 2.7 lists the meanings of the items in ATTRIBUTES. 15 1U ♦ + ♦ III + + + 13 12 11 10 63 9-8 7 6 5 U 3 2 1 +.«__ + + + - — + + 4. + +-_-+ 4 I I II III I I II + + -.-+ + --- ♦ - -- +- — ♦--- ♦ --- 4- ♦ + Device Status Word Bit Position* 1 2 3 H 5 f> 7 8 9-13 1U ■ 15 One Implies device will support multidataset activity device will handle output device will handle input device will handle binary data device will handle ASCII data driver has a special function entry driver has a CLOSE entry driver has an OPEN entry device is a terminal spares (not used) device is DECtape device is directory structured Table 2.7 Device Status Word 2. 2. 2. 20 ALLCC declaration: procedure ALLOC (F: file of character; DLKS: integer) ; parameters: F Contiguous file to be created BLKS L^nqth of file (nuirber of blocks) description: ALLOC performs the tile allocate function. Prior to invocation, the file block and link block associated with the *The bit position is also the index into the Boolean array ATTRIBUTES. Thus, ATTBIBUTES[ 1 U ] = True implies that the device in question is a DECtape. 6U fil^ must be init i t ia lized via a call to ASSIGN. 2.2.2,21 ASSIGN declaration: procedure ASSIGN (var F: file of character; DVC, UNIT, NAME1, NAME2, EXT, UIC: integer) ; parameters: F File whose link blocks and file blocks are to be initialized DVC Device where file resides (radix-50) UNIT Unit number of device NAME1 First word of filename (radix-50) NAME2 Second word of filename (radix-50) EXT Filename extension (radix-50) UIC UIC of owner of file description: ASSIGN initializes the file block and link block for the file F. In the current implementation of PASCAL, this information is stored as shown in Figure 2.2. If DVC is zero, then ASSIGN does not modify the link block. If UIC is zero, ASSIGN does not change the user ID code of the file block. 65 n I Address of Link Block I 1 T I 2 T I 3 I I 4 T Error Return Address I F I 5 1 Error Code I How Open I L E 6 T First Word of Filename I * B 7 1 Second Word of Filename I L 8 T Filename Extension I c K PI User ID Code (UIC) I i n I (spare) I Protect Code I L 111 Error Return Address I j H 12 I 00^000 Link Pointer I ** K 111 Logical Name of Dataset I B L U I Unit I of Words to Follow I C 15 I Physical Device Name I K Figure 2.2 File Block and Link Rlock * ftddress of file block, See Figure 2-6, page 2-b3 DOS Manual ** Address of link block, See Figure 2-5, page 2-61 DOS Manual 66 2. 2. 2. 22 PENAMECMD description: FFNAMF.CMD perforins the rename function. This function is divided into five parts: 1, 2. 3. 4, Masking S hi ft in g Add in g Changing Extension Chocking validity of new name 2. 2. 2. 22. 1 Masking Thp masking operation is done with the unsigned modulus function (UNMOD, see Section 2.2.2.31 for details). The number of characters to be masked out is the number of characters specified by the current inputdataset specifier. This value (INDATASET. NAMELEN) is determined by the procedure DATSF.TSPEC) (Section 2. 2. 1, 1) (See Table 2.8) 67 Number of Characters to be tasked 1 2 3 a 5 6 First Word of Name (N1) N1 mod 1600 N1 mod UO Ta ble : 2.8 Maskin g Fi: Lena me Second Word of Name (N2) N2 mod 1600 N2 mod U0 2.2.2.22.2 Shifting After the characters have been masked out of the old filename, the remaining characters will have to be shifted appropriately. The number of places to shift is determined by the difference in the number of characters specified in the input and output dataset filename specifiers (See Tables 2.9 and 2.10). Number of Positions to be shifted Left 1 2 3 a ^ First Word of Name (N1) N1*UO+N2/1600 N1*1600+N2/U0 N2 40* (N2 mod 1600) 1600* (N2 mod U0) Second Word of Name (N2) U0*(N2 mod 1600) 16 00* (N2 nod 4C) Table 2. 9 Shifting Filename Left 68 Number of Posit ions bo Shifted Piqht to First Word of Name (N1) Second Word of Name (N2) 1 2 3 U 5 6 N1/40 N 1/1 6 00 160C* (M1 mod U0) +N2/4C U0*(N1 mod 1600) +N2/16f>9 N1 N1/40 N1/1600 Table 2. 10 Shiftiny Filename night 2. 2. 2, 22. 3 Adding in New Characters To complete the changing of the filename, the radix-50 value for the new characters (specified in the output filename specifier) is added into the resultant name. 2. 2, 2. 22. U Chanqing Extension The extension is modified in a manner analogous to the process tor the filename. The process is somewhat simpler since the extension is only one word long. 2,2.2.22.5 Checking Validity of New Name When the new filename and extension have been determined, the new 69 filename is checked to ensure that it is vilid filename* and the UFD for the user is inspected to ensure that the new filename is not already there. 2.2.2.23 FASTCQPY declaration: procedure FASTCOPY; description: FASTCOPY implements the copying of one DECtape to another. The copying is done in two passes: first forward and then backwards with calls to the procedure THAN (see Section 2. 2.2.29) . 2.2.2.2U LTSTFILEKAME ♦Illegal filenames can be of two types: either the filename is null or it starts with a digit. For example, the command: */RF. = A* will produce a null filename when applied to the file A and an illegal filename when applied to the file A1. 70 declaration: procedure LISTFILENAME (NAME1, NAME2, EXT: integer): integer; parameters: NAME1 First word of filename (radix-50) NAME2 Second word of name (radix-50) EXT Filename extension (radix-50) description: LISTFILENAME outputs the name of the file and its extension to the keyboard. 2. 2. 2. 25 GETUIC (ieclarat ion : function GETUIC: integer; description: GETUIC returns the UIC of the user currently logged in on the system. 2. 2. 2. 26 LESSTHAN declaration: function LESSTHAN (A, D: integer); Boolean; parameters: A B Numbers to be compared 71 description: LESSTHAN performs an unsiqned comparison between A and B, It returns True if A is less than B. 2.2.2.27 ERPOP declaration: procedure EFROR (MESSAGE: text) ; parameter: MESSAGE Error message to be printed description: ERROR outputs the error message passed to it and aborts the command by doing an EXIT. 2. 2. 2.28 TODAY declaration: function TODAY: integer; description: TODAY returns the current date in modified Julian, The modified Julian date is: (Year - 1970) * 1000 ♦ day of year. 72 2.2.2.29 TPAN declaration: procedure TPAN (BLOCK: integer; vdr BUFFS?.: array [ *, . bu tsize ] ot integer; F: file of character; DIRECT: integer) ; parameters: BLOCK Device block number BUFFER Array to be read or written F File variable on device where TRAN is to be performed DIRECT Direction of transfer description: TRAN performs TRAN level reguests. The direction of the transfer is determied by DIRECT. The possible values of DIRECT are: 2 Write 4 Pead 205^* Reverse write 20S2* Reverse read 2. 2. 2. 30 UNDTV declaration: function UNDIV (A, B) : integer; parameters: A Dividend B Divisor description: UNDIV returns the guotient of A divided by B where A is taken as an unsigned number and B is either U0 or 1600 Applicable to DECtape only. 73 (decimal) . 2.2.2.31 UNMOD declaration: function UNMOD: (A,B: integer): integer; parameters: A B description: UNMOD performs the modulus function where A is an unsigned nuirber and B is UO or 1600 (decimal) . If A is positive, UNMOD returns A mod B. If A is negative, UNMOD returns (1536 ♦ A) mod B, When A is negative, the unsigned value of A is 65536 ♦ A. Therefore: val (A) = 65536 + A val (A) = 6UC00 ♦ 1536 ♦ A Thus for B = UO: A mod UO = (6unO0 «■ 1536 ♦ A) mod UO A mod UO = (6U000 mod UO ♦ [1536 ♦ A] mod UP) mod UO A mod UC = (0 + r 1 536 ♦ A] mod UO) mod UO A mod UO = (1536 ♦ A) mod UO Similary for B = 1600: A mod 1600 = (6U000 + 1536 + A) mod 1600 A mod 16C0 = (6U00 mod 1600 ♦ [1536 ♦ A] mod 1600) mod 1600 7a A mod 1600 = (C + [1536 ♦ A} mod 16C0) mod 1600 A moi 1600 = (1536 + A) mod 16C0 2. 2. 2. 32 UNMPY declaration: function: UNMPY (A, B) : integer; parameters: A Multiplicand B Multiplier description: UNMPY returns the unsigned product of A and B, where B is either 40 or 1600. 2. 2. 2. 33 UNPACK declaration: procedure UNPACK (var F: file of character; VAL: integer) ; description: UNPACK converts the radix- 5G strinq in VAL into ASCTJ and outputs it to thp file F. 75 2.2.2.34 UNPACKDATE declaration: procedure UNPACKDATE (JULIAN: integer); parameter: JULIAN Date (modified Julian) description: UNPACKDATE converts JULIAN to the date it represents (DD-MMM-YY) and outputs it to the current output file. 2. 2.2.3S VALIDFILE declaration: function: VALIDFILE (NAME1, NAMF2, EXT: integer): Boolean; parameters: NAME1 First word of filename NAME2 Second word of filename FXT filename extension description: VALIDFILE checks to see if there is a file with the given name and extension in the current output user's UFD. If there is not, (eof is True) , VALIDFILE returns True, If the file already exists (eof is raise) then one of three things is done: 1. If the update flag is set (UPDATE) the file is deleted and VALIDFILE returns True. 2. If the output UIC is not that of the user currently logged in, an error message is printed and the command is aborted. 3. If the output UIC is that of the user logged in, the user is asked if he wants to update, i. e, , rewrite the file. If the user responds with 'Y', the tile is deleted and VALIDFILE returns True. If the user responds with anythinq other than 'V (except ' A • , returns False. see Section 2.2.2.18) VALIDFILF 76 77 2. 3 MAINTAINING PIP The precedinq sections describe the procedures and data structures utilized by PIP. The program may be modified by adding switches. Of the two types of switches, qualifying switches are most easily added. 2.3.1 QUALIFYING SWITCHES If addition qualifying switches are desired, the following steps are necessary: 1. Chanqe the type SWITCHTYPE to include the new switch. 2. Modify the pxternal procedure INIT to initialize the switches name. 3. Then, if the switch is to be used to restrict files, determine which of the fields of the file are affected and change DATA5ETSPEC to set the appropriate elements of LOBND and UPBND. 2. 3. 2 ACTION SWITCHES If additional commands ace to be added to PIP the following steps are required* ♦The only changes necessary would be in the procedure DATASETSPEC. 78 1. Change the type SWITCHTYPE to include the new s witch 2. Modify INTT in initialize the name of the switch and to set the arrays OWNERCMD and USRMUSTBETHERE. 3. Write the required procedures to implement the command . 2,3.3 POSSIBLE EXTENSIONS The number of possible extensions is practically unlimited. Three possible extension are given below. 2.3.3.1 MODIFICATION OF ENTER COMMAND Ol^e useful extension of PIP would be to have an optional value specifier with the /EN switch consisting of the name by which the user wishes to be identified. These pre-defined UIC's are currently stored in the file SYSHDR.STF. 2.3.3.2 MODIFICATION OF THE /LT AND /GT SWITCHES It might be useful to have value specifiers associated with these switches, i. e, , /GT: A. B/LT:X. Y/DI 79 miqht be a possible syntax to specify all files with filenames between A. B and X. Y. The current data structure of PIP would support such an extension without any modifications. 2.3.3.3 Binary Output of Files In some instances, the user may wish to examine a binary file either in binary or in octal. The addition of the switch /BI for binary output to either the line printer or keyboard would facilitate this action. 80 BIBLIOGRAPHY Digital Equipment Corporation, DOS/BATCH Software Support Manual, Order number DEC-1 1-OSSMA- D, 1974. Digital Fquipment Corporation, MACRO-11 Assembler Programmer's Manual Order number DEC-1 1-OMACA-A-D, June 1972. Digital Equipment Corporation, PDP-11 Disk Operating System Monitor Programmer's Handbook, Order number D^C-1 1-0M0NA-A-D, October 1972. Digital Eguipment Corporation, PDP-11 File Utility Package (PIP) for the Disk Operating System, Order number DEC-1 1-PIDB-D, September 1971. BIBLIOGRAPHIC DATA SHEET 1. Report No. UIUCDCS-R-77-877 I. Title and Subtitle Peripheral Interchange Program (PIP) 3. Recipient's Accession No. 5. Report Date May 1977 7. Author(s) Douglas J. Wylie 8. Performing Organization Rept. No. J. Performing Organization Name and Address Department of Computer Science University of Illinois Urbana, Illinois 61801 10. Project/Task/Work Unit No. 11. Contract /Grant No. NSF DCR 72-03740 A01 12. Sponsoring Organization Name and Address National Science Foundation Washington, DC 13. Type of Report & Period Covered 14. 15. Supplementary Notes 16. Abstracts PIP is a program which maintains the file structure of the PDP-11 Disk Operating System. The version of PIP described in this document is written in Pascal-11, thus permitting the quick and simple implementation of many expanded features. These include sorted directories, a greatly expanded switch facility, and greater flexibility in specifying file names. 17. Key Words and Document Analysis. 17o. Descriptors PDP-11 » Pascal-11 PIP file handling 17b. Identifiers/Open-Ended Terms 17c. COSATI Field/Group 18. Availability Statement FORM NTIS-35 (10-70) 19. Security Class (This Report) UNCLASSIFIED 20. Security Class (This Page UNCLASSIFIED 21. No. of Pages 22. Price USCOMM-DC 40329-P7I •fc£p 1 6 1977 UNIVERSITY OF ILLINOIS-URBANA 510 MILBHno.C002no.S74-l79(H7T INDUCE-1 an Interactive Inductive Inle 3 0112 088403453