900 Series HP 3000 Computer Systems Accessing Files Programmer's Guide ABCDE HP Part No. 32650-90017 Printed in U.S.A.
The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or tness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions.
iv
Preface MPE/iX, Multiprogramming Executive with Integrated POSIX, is the latest in a series of forward-compatible operating systems for the HP 3000 line of computers. In HP documentation and in talking with HP 3000 users, you will encounter references to MPE XL, the direct predecessor of MPE/iX. MPE/iX is a superset of MPE XL. All programs written for MPE XL will run without change under MPE/iX.
Chapter 12 Chapter 13 Sharing a File discusses methods you can use to share a le with other users. Maintaining File Security describes how you can maintain secure les and Chapter 14 Getting File Information describes the intrinsics you can use to obtain Appendix A vi restrict le access. information about le. HP Pascal Program Example o ers you HP Pascal program examples to help you better understand how to use le system intrinsics to perform le access tasks.
Conventions UPPERCASE In a syntax statement, commands and keywords are shown in uppercase characters. The characters must be entered in the order shown; however, you can enter the characters in either uppercase or lowercase.
Conventions (continued) [ In a syntax statement, brackets enclose optional elements. In the following example, OPTION can be omitted: ] COMMAND lename [OPTION] When several elements are stacked within brackets, you can select one or none of the elements. In the following example, you can select OPTION or parameter or neither. The elements cannot be repeated. COMMAND [ ...
NOTATION base pre xes DESCRIPTION The pre xes %, -, and $ specify the numerical base of the value that follows: %num speci es an octal number. -num speci es a decimal number. $num speci es a hexadecimal number. When no base is speci ed, decimal is assumed. Bit (bit:length) When a parameter contains more than one piece of data within its bit eld, the di erent data elds are described in the format Bit (bit:length), where bit is the rst bit in the eld and length is the number of consecutive bits in the eld.
Contents 1. Introduction Disk Files and Device Files . . . . . . . . . . . . . . . . . . . . . . . . . . Topics in this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. Creating A File The HPFOPEN Intrinsic . . . . . . NOWAIT I/O . . . . . . . . . . . NOWAIT I/O intrinsics . . . . . . Aborting NOWAIT I/O . . . . . . Limitations . . . . . . . . . . . The FOPEN Intrinsic . . . . . . . . The BUILD Command . . . . . . . The FILE Command . . . . . . . . Summary of Overrides . . . . . . .
4. Specifying a File Domain New Files . . . . . . . . Temporary Files . . . . . Permanent Files . . . . . Changing Domains . . . . Searching File Directories Listing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing a File Label to a Labeled Tape File . . . . . . . . . . . . . . . . . . Writing User Data in ANSI Labels . . . . . . . . . . . . . . . . . . . . . . . 9. Reading from a File Sequential Access and Random Access . . . . . Reading from a disk le using sequential access Reading from a disk le using random access . Increasing I/O performance using FREADSEEK Reading From $STDIN . . . . . . . . . . . . . Reading From a Magnetic Tape File . . . . . . . Reading a File Label from a Labeled Tape File . .
Log of system logging con guration . . . . . . . Log of restore . . . . . . . . . . . . . . . . . Log of printer access failure . . . . . . . . . . Log of stream initiation . . . . . . . . . . . . Log of user logging . . . . . . . . . . . . . . . Log of process creation . . . . . . . . . . . . . Logging a speci c user . . . . . . . . . . . . . . Logging le security related events . . . . . . . . Log of password changes . . . . . . . . . . . . Log of ACD changes . . . . . . . . . . . . . .
Figures 1-1. 1-2. 2-1. 2-2. 2-3. 2-4. 2-5. 3-1. 3-2. 3-3. 3-4. 3-5. 5-1. 6-1. 7-1. 7-2. File System Interface . . . . . . . . . . . . . . . . . Records/Files Relationship . . . . . . . . . . . . . . . File System Hierarchy of Overrides . . . . . . . . . . . Fixed-Length Records . . . . . . . . . . . . . . . . . Variable-length Records . . . . . . . . . . . . . . . . Unde ned-Length Records . . . . . . . . . . . . . . . Record Placement for ASCII Files . . . . . . . . . . . .
Tables 2-1. 2-2. 2-3. 2-4. 2-5. 2-6. 2-7. 3-1. 3-2. 3-3. 3-4. 3-5. 4-1. 4-2. 5-1. 7-1. 12-1. 12-2. 13-1. 13-2. 13-3. 13-4. 13-5. 13-6. 14-1. 14-2. 14-3. HPFOPEN Itemnum/Item Values . . . . . . . . . . . . FOPEN/HPFOPEN Parameter Equivalents . . . . . . . . Determining a File's Physical Characteristics Using FOPEN FILE, FOPEN, and HPFOPEN Parameters . . . . . . . . Comparison of Logical Record Formats . . . . . . . . . Standard Default Record Sizes . . . . . . . . . . . . . Reserved File Codes . . . . . .
1 Introduction Almost every kind of organization in our modern society is concerned in some way with information. Corporations keep track of their business dealings, political groups keep lists of potential voters, and families remember whose turn it is to do the dishes. When an organization needs to deal with large amounts of information in an e cient, dependable manner, a computer can be an indispensable aid.
Figure 1-2. Records/Files Relationship Since all input/output operations are done through the mechanism of les, you may access very di erent devices in a standard, consistent way. It does not make much di erence to you whether you read your le from a disk or from a magnetic tape, because the le system permits you to treat all les in the same way.
Disk Files and Device Files The le system recognizes two basic types of les, classi ed on the basis of the media on which they reside when processed: 1. Disk les, which are les residing on disk, are immediately accessible by the system and potentially shareable by several jobs/sessions at the same time. 2. Device les are les currently being input to or output from any peripheral device except a disk.
A special method of accessing a le, called update access, is discussed in chapter 10, \Updating a File." You can access a le mapped directly through memory loads and stores, thus bypassing the overhead associated with accessing the le through le system intrinsics. Chapter 11, \Accessing a File Using Mapped Access" describes mapped access of a le and the applications where mapped access may increase your program's performance.
2 Creating A File When you create a le, you choose the attributes that le will have; your choices are made on the basis of how the le will be used. A le's physical characteristics are determined by the parameters you choose when you create the le with the HPFOPEN/FOPEN intrinsic or the BUILD command, or when you specify the le with the FILE command. Once a le has been created, its physical characteristics cannot be changed.
NOWAIT I/O has been available to users of standard les for a long time, but to use it on standard les requires privileged mode. On standard les the mechanics of NOWAIT I/O prevent MPE/iX from protecting a process from corrupting its own stack; however, because message les work di erently, NOWAIT I/O on message les does not require privileged mode. NOWAIT I/O intrinsics To perform a NOWAIT I/O, the FREAD or FWRITE intrinsic must be called to initiate the transfer.
Table 2-1. HPFOPEN Itemnum/Item Values Itemnum Mnemonic Item Description 0 2 CA 3 I32 5 I32 6 I32 End of option list: There is no corresponding item. The absence of an itemnum after the last itemnum,item pair is equivalent to specifying this option. Formal designator: Passes a formal le designator, following MPE/iX le naming conventions. The le name must begin with an alphabetic character and contain alphanumeric characters, slashes, or periods.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-4 7 I32 8 CA 9 I32 10 I32 12 I32 Creating A File Carriage-control: Passes a value indicating whether or not a carriage-control directive is supplied in the calling sequence of each FWRITE call that writes records onto the le. This option is applicable only at le creation. Carriage-control is de ned only for ASCII les.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 13 I32 14 I32 15 I32 16 I32 17 I32 Exclusive: Passes a value indicating continuous exclusive access to the le, from open to close. Use this option when performing a critical operation (for example, updating the le). Default: 0 (ASC) This option is not used for printers. Multiaccess: Passes a value indicating how the le's record pointer is to be shared.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-6 18 @32 19 I32 Creating A File Short-mapped: Returns a short pointer to the beginning of the data area of the le. This option maps the le into short pointer space. A short-mapped le can be 4 megabytes in length. The calling process can have up to 6 megabytes of short-mapped les open at a time. Use the pointer as a large array of any type to e ciently access the le.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 20 CA 22 CA Device name: Passes the logical device number, in ASCII form, of a speci c device. The le is assumed to be permanent. If the device name option is speci ed, the nonshareable device should be ready prior to the HPFOPEN call (otherwise, an error results).
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-8 23 CA 24 I32 25 CA Creating A File Volume name: Passes a character array representing a volume name that restricts the le speci ed to a speci c volume. The volume must reside within the volume set of the group where the le resides. This option is applicable only at le creation.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 26 CA 27 I32 28 CA Remote environment: Passes the node name of the remote computer where the le is located. This option is used when referencing a le located on a remote computer. Default: No node name passed (local le access). A character placed in the rst element designates the delimiter used by HPFOPEN to search for the end of the character array.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-10 29 I32 30 I32 31 CA Creating A File Privileged access: Passes a value that temporarily restricts access to the le number returned from HPFOPEN to a calling process whose execution level is equal to or less than the value speci ed in this option. This restriction lasts until the le associated with the restricted le number is closed. Do not specify a value less than the execution level of the calling process.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 32 CA Labeled tape sequence: Passes one of the following character arrays indicating the position of the le in relation to other les on the tape: 0 Causes a search of all volumes until the le is found. 1.. Speci es the position of the le relative to the current 9999 le on the tape. Causes the tape to be positioned so as to add a new le at the end of the volume or last volume in a multivolume set.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-12 34 I32 35 I32 36 I32 Creating A File Spooler copies: Passes a value in the range 1..127 indicating the number of copies of the entire le to be produced by the spooling facility. This option is applicable to spooled devices only. This option can be speci ed for a le already opened (for example, $STDLIST), where the highest value supplied before the last FCLOSE takes e ect.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 37 I32 38 I32 File code: Passes a value that can be used as a le code to identify the type of le. This code is recorded in the le label and is accessible through the FFILEINFO intrinsic. This option is applicable only at le creation (except when opening an old le that has a negative le code). If the program is running in user mode, specify a le code in the range 0..32,767 to indicate the le type being created.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-14 39 I32 40 I32 41 42 CA Creating A File Access type: Passes a value indicating how to use the le, either sequentially or randomly. The le system uses this information to determine the most e cient prefetching algorithm to improve the performance of the le access. Default: 0 (ASC) Not used for asynchronous devices. Block factor: Passes the number of logical records to be contained in one physical record (block).
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 43 record 44 I32 45 CA UFID: Passes a unique le identi er (UFID) to provide a fast opening of an old disk le. A UFID is a record structure, 20 bytes in length, that uniquely identi es a disk le. Using this option avoids a directory search. Obtain the UFID of an opened le by calling FFILEINFO. The UFID can then be passed to HPFOPEN. The le represented by the UFID must be accessible to the process calling HPFOPEN.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-16 46 I32 47 I32 48 I32 49 50 I32 Creating A File Inhibit bu ering: Passes a value enabling/disabling automatic bu ering by MPE/iX. If NOBUF is speci ed, I/O is allowed to take place directly between the data area and the applicable hardware device. Default: 0 (ASC) Not used for asynchronous devices. Numextents: Passes a value in the range 1..32 that determines the number of extents for the le.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 51 52 CA 53 I32 Pascal/iX string: Passes a formal le designator, following MPE/XL le naming conventions, but using the Pascal/iX STRING type format. This option is identical to itemnum=2 except for the type of item. No delimiters are needed. Default: No string passed.
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 2-18 54 REC 55 56 I32 57 58 59 60 61 64 BA Creating A File KSAM parm: Passes a record that de nes the keys for a new KSAM le. (KSAM XL) For KSAM XL les, refer to the parm parameter discussion in the Using KSAM XL (32650-90168). (KSAM/3000) The record must be at least 34 bytes in size. For details, refer to the ksamparam parameter discussion in the KSAM/3000 Reference Manual (30000-90079).
Table 2-1. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 74 Header/Trailer: Enable/disable standard headers/trailers: 0 Enable header and trailer (default) 1 Disable header 2 Disable trailer 3 Disable header and trailer Provides a standard way for the spooler to control the printing banners. Valid only for the initial HPFOPEN call to the printer and prevents the header from being printed. On the last FCLOSE, the trailer is not printed.
Table 2-2.
Table 2-2. FOPEN/HPFOPEN Parameter Equivalents (continued) FOPEN Parameter HPFOPEN Itemnum,Item numbu ers: Bits (11:5) numbu ers Bits (4:7) spooler copies Bits (0:4) output priority lesize 44, numbu ers 34, spooler copies 27, output priority 35, lesize numextent 47, numextent initialloc 36, initial allocation lecode 37, lecode Table 2-3.
The FILE Command The FILE command is used to determine how a le will be accessed. You may use FILE to describe any of the characteristics available with HPFOPEN/FOPEN or BUILD, but you cannot actually create a le with the FILE command. While HPFOPEN/FOPEN and BUILD physically allocates space for a le and de ne its characteristics, the FILE command may only de ne how a le will be accessed at run time.
Table 2-4.
Table 2-3.
Table 2-3.
Figure 2-1. File System Hierarchy of Overrides Since the physical characteristics of a le cannot be changed after it has been created, it makes sense that the le label would take precedence over all commands. Other determinants are e ective only when a new le is being created. Note FILE commands and HPFOPEN/FOPEN calls cannot alter physical characteristics of an existing le.
Fixed-length records When you create a le and request xed-length records, all the records in the le will be the same size. The le system knows how much space has been allocated for each record, and that all of the space is to be available for data. Figure 2-2 depicts a le with xed-length records. A record size of n bytes has been speci ed. Note that each record is the same size and contains the same amount of information. Figure 2-2.
Variable-length records There may be a time when you want a disk le in which the logical records need not be the same size. In this case, you can request that the format of the records be variable-length. The le system knows the size of each logical record because each record is preceded by a two-byte (16-bit) counter giving the length of the record in bytes; thus, the data for each record is accompanied by an indication of its length.
Unde ned-length records When your le contains unde ned-length records, the le system does not know the amount of good data in any given logical record. The data length is \unde ned." Unde ned-length records are especially useful when you are reading tapes of unknown record length produced on other systems.
Table 2-5. Comparison of Logical Record Formats Fixed-Length Variable-Length Unde ned-Length Data length known to le system. Same length for all records. Record space contains data only. Request actual size for records. Data length known to le system. Record length varies. Record space contains data plus byte count. Request maximum size for records. Data length not known to le system. Same length for all records. Record space contains data plus ller. Request maximum size for records.
Circular les Circular les are wrap-around structures that behave as standard sequential les until they are full. As records are written to a circular le, they are appended to the tail of the le; when the le is lled, the next record added causes the block at the head of the le to be deleted and all other blocks to be logically shifted toward the head of the le. Circular les may not be simultaneously accessed by both readers and writers.
Specifying Record Size You can specify the size of the records in your le by using the BUILD (for disk les) or FILE commands, or the HPFOPEN/FOPEN intrinsic; however, the interpretation of the requested record size can be a ected by the record structure and data format chosen as well as the device for the le.
Figure 2-5. Record Placement for ASCII Files Rather than specify your own record size, you can accept the default record size for the device that you are using. Default record sizes are listed in Table 2-6. Note that subsystem defaults may be di erent from MPE defaults; for example, the Editor default may be 72 or 80 bytes (depending on text format) while the MPE standard default is the record size con gured for the device. Table 2-6.
Specifying Disk Volume Restrictions MPE/iX makes a distinction between the device and the media. The device is the disk drive and the media is the disk pack. The MPE/iX volume management facility controls the media and divides the media into three entities: Volume set, a set of related disk packs assigned to the group in which you create your le. Volume class, a subset of a volume set. A volume can be assigned to more than one volume class. Volume, a single disk pack.
For instance, on the second run, you might wish to classify the le with the le code 2, as follows: File code | FILE DESGX=DESGB;CODE=2 RUN FILEPROD If you later wished to determine the classi cation to which this le belonged, you could use the LISTFILE command with an information level of 1, which prints the le name, le code, and other information about the le. Alternatively, you could determine the le code by calling the FFILEINFO intrinsic.
Integer 1024 1025 1026 1027 1028 1029 1031 1035 1036 1037 1040 1041 1042 1050 1051 1052 1054 1055 1056 1057 1058 1059 1060 1070 1080 1083 1084 2-36 Mnemonic USL BASD BASP BASFP RL PROG SL VFORM VFAST VREF XLSAV XLBIN XLDSP EDITQ EDTCQ EDTCT TDPDT TDPQM TDPP TDPCP TDPQ TDPXQ RJEPN QPROC KSAMK GRAPH SD Creating A File Table 2-7.
Integer 1090 1100 1101 1102 1103 1110 1112 1113 1114 1130 1131 1132 1133 1139 1140 1141 1145 1146 1147 1148 1149 1152 1153 1156 1157 1158 1159 1166 1167 1168 1169 Reserved File Codes (cont.
Integer 1170 1171 1172 1173 1174 1175 1176 1177 1178 1192 1193 1194 1195 1211 1212 1213 1214 1215 1216 1217 1226 1227 1228 1229 1230 1236 1242 1243 1244 1245 2-38 Creating A File Reserved File Codes (cont.
Integer 1246 1258 1259 1270 1271 1272 1273 1275 1276 1401 1421 1422 1425 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1441 1476 1477 1478 1479 1480 Reserved File Codes (cont.
Reserved File Codes (cont.) Mnemonic Meaning Integer 1483 1484 1485 1486 1491 1500 1501 1502 1514 1515 1516 1517 1521 1526 1527 1528 3333 Note VCGPM FRMAT DUMP NNMD0 X4HDR WP1 WP2 LO123 FPCF INSP OUTSP CHKSP DSKIT MSACK MSNON MSTRC Virtuoso Core Generator Processed Macro File Formatter Dump Files Created and Used by IDAT and DPAN New Wave Mail Distribution List X.
Specifying Storage Format Devices on the HP 3000 can transmit information in ASCII (American Standard Code for Information Interchange) and/or binary code, depending on the device. For example, a line printer handles ASCII formatted data, while a disk can transmit and store data in either format. You can use appropriate optional parameters in HPFOPEN/FOPEN to specify the code (ASCII or binary) in which a new le is to be recorded when it is written to a device that supports both codes.
3 Specifying a File Designation The name by which a program recognizes your le is its formal le designator. This is the le name that is coded into the program, along with the program's speci cations for the le. The formal le designator is the name by which your program recognizes the le, but there must also be a means by which the le system can recognize it, allowing it to be referenced by various commands and programs.
User-De ned Files You can reference any user-de ned le by writing its name and descriptors in the lereference format, as follows: lename[/lockword][.groupname][.accountname] In no case must any le designator written in the lereference format exceed 35 characters, including delimiters.
period. Embedded blanks are not permitted. As an example, suppose you are logged on under the account named MYACCT but wish to reference the le named GENINFO in the public group of the system account. Your program references this le under the formal designator GENFILE. You would enter: FILE GENFILE=GENINFO.PUB.SYS A le reference that includes the le name, group, and account is called a fully quali ed le name.
referencing lockwords are shown below; the last command illustrates the complete, fully quali ed form of the lereference format. FILE AFILE=GOFILE/Z22 <---- Lockword FILE BFILE=FILEM/LOCKB.GRO7 | |---- Lockwords | FILE CFILE=PAYROLL/X229AD.GROPN.ACCT10 A le may have only one lockword at a time. You can change or remove the lockword by using the RENAME command or the FRENAME intrinsic. You can also initially assign a lockword to an existing le with this command or intrinsic.
System-De ned Files System-de ned le designators indicate those les that the le system uniquely identi es as standard input/output devices for jobs and sessions. These designators are described in Table 3-1. When you reference them, you use only the le name; group or account names and lockwords do not apply. Table 3-1.
You could enter the following commands: FILE INFILE=$STDIN FILE OUTFILE=$STDLIST RUN MYPROG Input/Output sets All le designators can be classi ed as those used for input les (Input Set), or those used for output les (Output Set). For your convenience, these sets are summarized in Table 3-2 and Table 3-3. File Designator $STDIN $STDINX $OLDPASS $NULL *formaldesignator lereference File Designator $STDLIST $OLDPASS $NEWPASS $NULL *formaldesignator lereference Table 3-2.
le opened to the same teleprinting terminal (for a session) would constitute an interactive pair. An input le and a list le are said to be duplicative when input from the former is duplicated automatically on the latter. For example, input from a magnetic tape device is printed on a line printer. You can determine whether a pair of les is interactive or duplicative with the FRELATE intrinsic call.
Figure 3-1. Passing Files between Program Runs .. . FILE SOURCE1=DSFIL FILE INTERFIL=$NEWPASS RUN PROG1 FILE SOURCE2=$OLDPASS RUN .. PROG2 . <--|- Same File <--- A program le must pass through several steps as it is executed; passed les are most frequently used between these steps. A program le must be compiled and linked before it is executed. By default, the compiled form of a text le is written to $NEWPASS.
Figure 3-2. Passing Files within a Program Run $NEWPASS and $OLDPASS are specialized disk les with many similarities to other disk les. Comparisons of $NEWPASS to new les, and $OLDPASS to old les, are given in Table 3-4 and Table 3-5.
Table 3-4. New Files Versus $NEWPASS NEW $NEWPASS Disk space allocated. Disk address put into control block. Default close disposition: Deallocate space. Delete control block entry. Disk address not saved (Not in any directory). Disk space allocated. Disk address put into control block. Default close disposition: Rename to $OLDPASS. Save disk address in current job or session table. (Job Information Table) Delete control block entry. Disk address saved for future use in the current job session. Table 3-5.
Parsing and Validating File Designators The FPARSE intrinsic parses and validates a le designator string to determine if it is syntactically correct. You can employ this intrinsic to check a formal le designator representing a le before attempting to open the le with HPFOPEN/FOPEN. MPE/iX le designators used for the le system and two user interface commands include a remote environment ID (envid).
Figure 3-4. Illustration of FPARSE Usage In Figure 3-5, below, the le string is "$OLDPASS": Figure 3-5. Illustration of FPARSE Usage Note that \$" is a special exception to the rules of le names and is considered part of the le name, unlike \*", which is not.
4 Specifying a File Domain One way to classify a le is on the basis of its domain. A le can be permanent or temporary, or it may exist only to one particular process. The le system maintains separate directories to record the location of temporary les and permanent les. Of course, there is no le system directory for les that exist only to their creating process (new les).
Permanent Files A permanent le exists as a le in the system le domain. Its existence is not limited to the duration of its creating job or session, and depending on security restrictions, it may be accessed by jobs or sessions other than the one that created it. Some or all of the space for a permanent le has already been allocated, and its physical characteristics have been de ned. Table 4-1.
Changing Domains A le need not always stay in the same domain. Any disk le can be made permanent, or can be deleted when it has served its purpose. The disposition parameter of the FCLOSE intrinsic can specify a di erent domain for a le as it closes, or the FILE command can be used to change the domain of a le. The DEL, TEMP, and SAVE parameters determine what happens to the le when it is closed. For details about how the FCLOSE intrinsic handles le domain disposition, refer to chapter 6, \Closing a File".
Searching File Directories There are two directories with addresses of les: the temporary le directory (job le domain) for the addresses of temporary les and the permanent le directory (system le domain) for the addresses of permanent les. There is no directory for new les. When both directories are searched for a le address (for example, when you open a le with the domain option set to OLD), the temporary le directory is searched rst.
5 Opening a File Before your program can read, write, or otherwise manipulate a le, the program must initiate access to that le by opening it with the HPFOPEN/FOPEN intrinsic call. This call applies to both disk les and device les. This chapter discusses how you can use HPFOPEN to open various types of les supported by MPE/iX. Examples of program segments are provided to illustrate HPFOPEN calls.
Constructing the control blocks required by MPE/iX for this particular access of the le. The information in these blocks is derived by merging speci cations from four sources, listed below in descending order of precedence (and illustrated in Figure 5-1): 1. The le label, obtainable only if the le is an old le on disk; otherwise, device-dependent characteristics applicable to the nonshareable device. This information overrides information from any other source. 2.
(indicating the next sequential record to be accessed) for each access where you did not request or permit the multiaccess option at HPFOPEN/FOPEN time. Which to Use: HPFOPEN or FOPEN The HPFOPEN intrinsic is the recommended intrinsic for creating and opening les on an MPE/iX-based computer system. HPFOPEN is designed to be more exible and extendible than the FOPEN intrinsic. In addition, HPFOPEN's available options are a superset of the options available through FOPEN.
Opening a new disk le Example 5-1 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that opens a new disk le to be used with a text editor. The text editor accesses only standard ASCII text les with xed-length records, each record 80 bytes in size. Knowing this, you can specify the appropriate HPFOPEN options, and allow others (speci cally, domain option, record format option, and le type option) to default to the desired characteristics.
If the HPFOPEN call is successful, a positive integer value is returned in file_num, and status returns a value of zero. The new disk le is now open and can be accessed with system intrinsics. If an error or warning condition is encountered by HPFOPEN, status returns a nonzero value, thus invoking the error-handling procedure handle_file_error. In appendix A, \HP Pascal/iX Program Examples," Example A-1 uses a similar procedure to open a new disk le.
Opening a permanent disk le Example 5-2 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that opens a permanent disk le that is to be shared among multiple concurrent accessors. Note the use of the dynamic locking option to enable the use of le-locking intrinsics (FLOCK and FUNLOCK) with this le. The le is opened update access to allow opening the le with Read/Write access without a ecting the current EOF. Thus, current data in the le is retained. Example 5-2.
HPFOPEN (file_num, status, formal_designator_option,file_name, domain_option, permanent, access_type_option, update, dynamic_locking_option, lockable, exclusive_option, shared, ASCII_binary_option, ascii ); {formaldesignator option} {domain option} {access type option} {dynamic locking option} {exclusive option} {ASCII/binary option} if status <> 0 then handle_file_error (file_num, status); end; The le name passed in the formaldesignator option contains MPE/iX command interpreter variables and expression
Opening $STDIN Example 5-3 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that uses only the designator option to open the system-de ned le $STDIN. $STDIN is the le designator associated with your job or session's standard input device. For an interactive session, $STDIN is always a terminal keyboard. For a batch job, $STDIN may be a disk le or other input device. You can also open a system-de ned le using only the HPFOPEN formaldesignator option (illustrated in Example 5-4).
Opening $STDLIST Example 5-4 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that uses the formaldesignator option to open the system-de ned le $STDLIST. $STDLIST is the le designator associated with your job or session's standard list device. For an interactive session, $STDLIST is nearly always a terminal screen. For a batch job, $STDLIST is usually a line printer. You can also open $STDLIST using the HPFOPEN designator option (illustrated in Example 5-3). Example 5-4.
Opening a Device File Device les are les that are currently being input to or output from a nonshareable device (any peripheral device except a disk). Because all le open operations are accomplished through the le system, you can open les on very di erent devices in a standard, consistent way, using the HPFOPEN or FOPEN intrinsics. Furthermore, the name and characteristics assigned to a le when it is de ned in a program do not restrict that le to residing on the same device every time the program is run.
New and permanent device les When a process accesses a device le (a le that resides on a nonshareable device), the device's attributes may override information passed in the domain option of the HPFOPEN/FOPEN call. Devices used for input only are considered permanent les. Devices used for output only, such as line printers, are considered new les. Serial input/output devices, such as terminals and magnetic tape drives, follow the domain option speci cation in your HPFOPEN/FOPEN call.
Opening an unlabeled magnetic tape le Example 5-5 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that opens an unlabeled magnetic tape le TAPEFILE. The intrinsic call assumes that the tape drive associated with device class TAPE supports a density of 1600 bpi. Example 5-5.
an error or warning condition is encountered by HPFOPEN, status returns a nonzero value, thus invoking the error-handling procedure handle_file_error. In appendix A, \HP Pascal/iX Program Examples," Example A-1 uses a similar procedure to open an unlabeled magnetic tape le. For more information about HPFOPEN parameters, refer to the MPE/iX Intrinsics Reference Manual (32650-90028).
Opening a labeled magnetic tape le Example 5-6 is an HP Pascal/iX code segment containing an HPFOPEN intrinsic call that opens a labeled magnetic tape le labltape. Use of the HPFOPEN labeled tape label option indicates to the le system that the le is opened as a labeled magnetic tape le. Example 5-6.
error or warning condition is encountered by HPFOPEN, status returns a nonzero value, thus invoking the error-handling procedure handle_file_error. In appendix A \HP Pascal/iX Program Examples," Example A-2 uses a similar procedure to open a labeled magnetic tape le. For more information about HPFOPEN parameters, refer to the MPE/iX Intrinsics Reference Manual (32650-90028).
6 Closing a File Once your program is nished accessing a le, the program can terminate access to the le with the FCLOSE intrinsic. This chapter discusses various ways that you can use the FCLOSE intrinsic to close disk les and device les. Examples are provided to illustrate important features available through the FCLOSE intrinsic.
Note Even though you are allowed to specify a le's nal disposition when the le is opened, MPE/iX does not search the appropriate directory until you attempt to close that le. If a con ict occurs between the dispositions speci ed at le-open time and le-close time, the disposition speci cation that has the lower positive-integer value takes precedence.
Example 6-1. Closing a New Disk File as Permanent .. . save_temp := 2; HPFOPEN(file_num, status, formal_designator_option, file_name, {HPFOPEN formaldesignator option} record_size_option, line_len, {HPFOPEN record size option} final_disp_option, save_temp, {HPFOPEN nal disp option } ASCII_binary_option, ascii {HPFOPEN ASCII/binary option} ); .. .
Closing a permanent disk le Example 6-2 closes the permanent le opened in Example 5-2. (Refer to Example 5-2 for details on this HPFOPEN call.) The disposition of the le is not changed when it is closed. The le remains a permanent disk le. Example 6-2. Closing a Permanent Disk File .. .
Closing a Magnetic Tape File The operation of the FCLOSE intrinsic as used with unlabeled magnetic tape is outlined in the owchart of Figure 6-1. Figure 6-1. Using the FCLOSE Intrinsic with Unlabeled Magnetic Tape Note that a tape closed with the temporary no-rewind disposition is rewound and unloaded if certain additional conditions are not met.
magnetic tape device using the device class option of HPFOPEN/FOPEN, then again open the already-allocated device by specifying its logical device number (ldev) using the device name option of HPFOPEN/FOPEN. This may be done in such a manner that both magnetic tape les are open concurrently. The second HPFOPEN/FOPEN does not require any operator intervention to allocate the device.
7 Record Selection and Data Transfer The chief activities of the le system involve the transfer of data. In this chapter we will examine how this is accomplished. As you read this chapter, keep these considerations in mind: How are records selected for transfer? What intrinsics are used for data transfer? How is the record pointer a ected by intrinsics? The last section of this chapter discusses the major points presented in this chapter as they pertain to magnetic tape les.
Figure 7-1. Record Pointers Following initialization, the record pointer may remain in position at the head of your le, or it may be moved by the intrinsics used in record selection.
array using a pointer declared in your program. Mapped les are discussed in chapter 11, \Accessing a File Using Mapped Access". Sequential access When you use this method of record selection, you assume that the record pointer is already where you want it. You transfer your data using the FREAD or FWRITE intrinsic, and the record pointer is automatically set to the beginning of the next record at the end of each read or write; for this reason, this method is also called serial record selection.
Table 7-1. Intrinsics for Data Transfer FREAD Used for sequential read. May be used with xed-length, variable-length, or unde ned-length record les. File must be opened with Read, Read/Write, or Update access. Successful read returns CCE condition code and transfer length; le error results in CCL condition code; end-of- le results in CCG condition code and returns a transfer length of zero. FWRITE Used for sequential write. May be used with xed-length, variable-length, or unde ned-length record les.
Multiple Record Transfers In almost all applications, programs conduct input/output in normal recording mode, where each read or write request transfers one logical record to or from the data stack. In certain cases, however, you may want your program to read or write, in a single operation, data that exceeds the logical record length de ned for the input or output le. For instance, you may want to read four 128-byte logical records from a le to your data stack in a single 512-byte data transfer.
Spacing To space forward or backward in your le, use the FSPACE intrinsic. Its syntax is FSPACE(filenum,displacement); The displacement parameter gives the number of records to space from the current record pointer. Use a positive number for spacing forward in the le or a negative number for spacing backward. You can use the FSPACE intrinsic only with les that contain xed-length or unde ned-length records; variable-length record les are not allowed.
Magnetic Tape Considerations The most common medium for storage of a device le is magnetic tape. This section describes the matters that you should keep in mind when you work with your magnetic tape les. Every standard reel of magnetic tape designed for digital computer use has two re ective markers located on the back side of the tape (opposite the recording surface).
FCONTROL (Write EOF). If a user program writes a logical end-of- le (EOF) mark on a magnetic tape over the re ective EOT marker, or in the tape trailer after the marker, hardware status is saved to return END-OF-TAPE on the next FWRITE. The le mark is actually written to the tape. FCONTROL (FORWARD SPACE TO FILE MARK). A user program that spaces forward to logical tape marks (EOFs) with the FCONTROL intrinsic cannot detect passing the physical EOT marker. No special condition code is returned.
8 Writing to a File This chapter describes, through program examples, various ways that you can use le system intrinsics to transfer data from your program to a disk le or a device le. This chapter is intended to illustrate topics introduced in chapter 7, \Record Selection and Data Transfer".
The following examples illustrate the use of le system intrinsics to perform sequential access writes and random access writes to a disk le. Writing to a disk le using sequential access Example 8-1 is an HP Pascal/iX code segment that copies logical records sequentially from an unlabeled tape le (indicated by variable tape_file_num) and uses FWRITE to write them to a disk le (indicated by variable disk_file_num). The operation is performed in a loop.
Writing to a disk le using random access Example 8-2 is an HP Pascal/iX code segment that reads records sequentially from old_disk_file and writes them into new_disk_file . Assume that both les have been opened already with calls to HPFOPEN/FOPEN. The end-of- le (EOF) using the FWRITEDIR of old_disk_file is determined with the FGETINFO intrinsic and assigned to the variable record_num. Example 8-2. Writing to a Disk File Using Random Access.
Writing to $STDLIST You can write data from your program to your program's standard list device $STDLIST using two intrinsics: PRINT FWRITE Normally, $STDLIST for jobs is a line printer and for sessions a terminal. You can write a string of ASCII characters from an array in your program to $STDLIST with the PRINT intrinsic. You do not need to use HPFOPEN/FOPEN to open the standard list device in order to use PRINT.
Writing Messages to the System Console Two intrinsics are available that allow you to print a character string directly from your program to the system console: PRINTOP transmits an ASCII character string from your program to the system console. PRINTOPREPLY transmits an ASCII character string from your program to the system console, and solicits a reply from the system operator.
Example 8-5. Writing a Message to the System Console and Requesting a Reply var . . . message : packed array [1..50] of char; {PRINTOREPLY parameter} length : shortint; {PRINTOREPLY parameter} zero : shortint; {PRINTOREPLY parameter} reply : packed array [1..31] of char; {PRINTOREPLY parameter} expected_length: shortint; {PRINTOREPLY parameter} counter . . .
data successfully, but return a CCL condition code until the tape crosses the EOT marker again in the reverse direction (rewind or backward). If the magnetic tape is labeled, a CCL condition code is not returned when the tape passes the EOT marker. Attempts to write to the tape after the EOT marker is encountered cause end-of-volume (EOV) labels to be written. A message then is printed on the operator's console requesting another reel of tape to be mounted.
Writing to a labeled magnetic tape le Example 8-7 is an HP Pascal/iX code segment that writes user-supplied data to the labeled magnetic tape le opened in Example 5-6. For information about the HPFOPEN call that returns the le number in the variable labeled_tape_file, refer to example 5-6. Example 8-7. Writing to a Labeled Magnetic Tape File var . . . control_code : 0..65535; record_length: shortint; file_record : record_type; . . .
Example 8-8 is an HP Pascal/iX code segment that writes a user-label to the labeled magnetic tape le opened in example 5-6. For information about the HPFOPEN call that returns the le number in the variable LABELED_TAPE_FILE, refer to example 5-6. Example 8-8. Writing a User-Label to a Labeled Magnetic Tape File. . . . var counter : integer; {Initialize counter } label_length : shortint; {FWRITELABEL length parm } user_label : packed array [1..80] of char; . . .
In order to retrieve the string recorded in bytes 5/21, you must create a program that uses the intrinsics FOPEN (or HPFOPEN) and FFILEINFO. The program must do two things: It must FOPEN (or HPFOPEN) the tape device. It must employ FFILEINFO with option 45 to retrieve the \ le" identi er. The tape containing such a label must be mounted before you run the program.
9 Reading from a File This chapter describes, through program examples, various ways that you can use le system intrinsics to transfer data to your program from a disk le or device le. This chapter is intended to illustrate topics introduced in chapter 7, \Record Selection and Data Transfer".
Reading from a disk le using sequential access Example 9-1 is an HP Pascal/iX code segment that uses the FREAD intrinsic to read records sequentially from a disk le. Example 9-1 contains a loop construct, where records are read sequentially from disk_file and written to the le new_file (both les opened elsewhere by HPFOPEN/FOPEN calls). The les are both standard ASCII les with xed-record format, each record 256 bytes in length.
Reading from a disk le using random access Example 9-2 is an HP Pascal/iX code segment that, within a loop construct, calls the FREADDIR intrinsic to read a record whose record number has been selected by the procedure select_record and returned in the variable record_number. The example then prints the selected record to the standard list device $STDLIST using the PRINT intrinsic. Example 9-2. Reading from a Disk File Using Random Access . . . var record : packed array [1..
chapter 8, \Writing to a File". For more information about opening a le, refer to chapter 5, \Opening a File". Increasing I/O performance using FREADSEEK If you know in advance that a certain record is to be read from a le with the FREADDIR intrinsic, you can speed up the I/O process by issuing an FREADSEEK intrinsic call. The FREADSEEK intrinsic moves the record from disk to virtual memory.
Example 9-3. Reading from $STDIN Using READ procedure get_file_designator (var file_name : packed array [1..80] of char); var message length control_code read_length expected_length : : : : : packed array [..
Reading From a Magnetic Tape File Example 9-4 is an HP Pascal/iX code segment that reads records sequentially from an unlabeled magnetic tape le (indicated by variable tape_file_num) and uses FWRITE to write them to a disk le (indicated by variable disk_file_num). The operation is performed in a loop. The loop ends when the FREAD intrinsic encounters an EOF marker on the tape (indicating the end of the tape le). Example 9-4.
Reading a File Label from a Labeled Tape File The FREADLABEL intrinsic is used to read a user-de ned label located on a labeled magnetic tape le or a labeled disk le. To read a user-de ned header label, the FREADLABEL intrinsic must be called before the rst FREAD is issued for the le. Execution of the rst FREAD causes MPE/iX to skip past any unread user-de ned header labels.
10 Updating a File You can use the FUPDATE intrinsic to update a logical record of a disk le. FUPDATE a ects the last logical record (or block for NOBUF les) accessed by any intrinsic call for the le named, and writes information from a bu er in the stack into this record. Following the update operation, the record pointer is set to indicate the next record position.
Example 10-1. Updating a Disk File procedure update_disk_file; {**************************************************************} { procedure update_disk_file updates records in the disk file } { with the replacement records read from $STDIN } {**************************************************************} var dummy inbuf end_of_file read_length begin : : : : integer; array [1..
In appendix A, \HP Pascal Program Examples," example A-5 is an HP Pascal/iX program that uses the procedure in example 10-1 to update records in a disk le. For more information about FUPDATE parameters, refer to the MPE/iX Intrinsics Reference Manual (32650-90028). Note A magnetic tape device is not designed to enable the update/replacement of a single record in an existing le.
11 Accessing a File Using Mapped Access A major enhancement to the MPE/iX le system is mapped le access, a method that allows you to access a le directly through memory load and store instructions. Mapped le access is available through two HPFOPEN intrinsic optional parameters: Item #18 short-mapped option returns a 32-bit value of type address. Item #21 long-mapped option returns a 64-bit value of type address.
Note When you access a le with mapped access you are bypassing le system services that set various le system pointers automatically, including the EOF and the logical record pointer. You are responsible for resetting the EOF prior to closing a le that you have accessed mapped. Also, le system posting is bypassed; so, if data recovery is needed you should use FCONTROL controlcodes 2 and/or 6 to post data and update the EOF periodically.
Long-mapped access Item #21 long-mapped option is available in the HPFOPEN intrinsic to provide you with access to large amounts of shared virtual memory. You can use the pointer as a large array of any type to e ciently access the le. A le created using the long-mapped option can be up to two gigabytes in size. There is no practical limit of the number of long-mapped access les that a process can have open at a time.
Example 11-1. Opening a Mapped File procedure Mapped_File_Example; type record_t = record {** defines an 80-byte record **} a_record : packed array [1..80] of char; end; file_t = array [1..50000] of record_t; {** define a 4,000,000 byte array **} var access,domain : integer; dummy : shortint; file_name : packed array [1..
begin {** initialize item values for the HPFOPEN **} file_name := '%EXAMPLE%'; create_domain_PERM := 4; domain_OLD := 3; filesize := 15265; read_write_access := 4; HPFOPEN ( ); {** create a short-mapped file **} file_number, status, file_name_option, file_name domain_option,create_domain_PERM, filesize option, filesize, short_mapped_option, file_ptr, access_type_option, read_write_access, {** put some data into the file **} for rec := 1 to 100 do for index := 1 to 80 do file_ptr^[rec].
12 Sharing a File Accessing and controlling a le that is open only to you is a relatively simple matter. When your le is being accessed by several users simultaneously, each user must be aware of special considerations for this shared le. As you read this chapter, keep these considerations in mind: How will others be allowed concurrent access to your le? Will the concurrent access need special management? Note In most cases, the following discussions pertain only to non-message les.
Table 12-1. File Sharing Restriction Options DESCRIPTION FILE ACCESS RESTRICTION PARAMETER Exclusive Access EXC Exclusive Write Access SEMI Shareable Access SHR After le is opened, prohibits concurrent access in any mode through another HPFOPEN/FOPEN request, whether issued by this or another program, until this program issues FCLOSE or terminates.
Table 12-2. Actions Resulting from Multiaccess of Files Semi-exclusive access This option allows other accessors to read the le, but prevents them from altering it. When appending new part numbers to a le containing a parts list, for instance, you might use this option to allow other users to read the current part numbers at the same time that you are adding new ones to the end of the le.
bu er content from the second user's output. To use Write access most e ectively with shared les, specify the multiaccess option as discussed below. To request share access for a le, use the SHR parameter in the FILE command, as follows: FILE RDFILE;SHR RUN RDPROG <---- Requests shared access Multiaccess This option extends the features of the share access option to allow a deeper level of multiple access.
Sharing the File Using FLOCK and FUNLOCK Sharing a le among two or more processes may be hazardous. When a le is being shared among two or more processes and is being written to by one or more of them, care must be taken to ensure that the processes are properly interlocked. For example, if process A is trying to read a particular record of the le, and at that time process B should execute and try to write that record, the results are not predictable.
13 Maintaining File Security MPE/iX provides two methods of establishing and maintaining le security. access control de nitions (ACD) for le and devices traditional le security For disk les only ACDs are implemented to provide a security mechanism that meets standards set forth by the National Computer Security Center. Traditional le security works through the mechanism long available on MPE systems. ACDs override any security measures implemented by traditional means.
Devices The System Manager (SM) is the owner of all of the devices on a system. How acds work When a user attempts to access a le or to acquire a device, HPFOPEN or FOPEN is called, and the system makes the following checks: Is the user an owner of the le or device; that is, is the user the creator of the le, the account manager (AM capability), where the le resides or the system manager (SM capability)? If so, permission is granted, and the checking ends.
Note If an ACD exists and if you are not explicitly given permission to access a le or a device, you do not have access. Managing ACDs with commands and intrinsics Use MPE/iX commands to manage ACDs interactively, through the command interpreter. Use MPE/iX intrinsics to manage ACDs in a program.
Preserving ACDs Device ACDs are not permanent objects; you must rede ne them every time that the system is rebooted. The easiest way to do this is to put ALTSEC commands into the SYSSTART le, either directly or in a command le. File ACDs are permanent objects; they do survive a reboot. When you store les to tape, FCOPY and STORE save the les' ACDs, too|unless you specify otherwise. If you are not an owner of the le and you do not have RACD permission, you get an error if you try to copy the ACD.
When you create a new le with the COPY, FCOPY, STORE, or RESTORE commands, you can use the command parameters to create the ACDs for the new le. COPY The COPY command automatically copies any ACD attributes from the source le to the target le, provided that the user is an owner of the source le or has RACD access to that le. COPY FILEA,FILEB FCOPY The ;COPYACD parameter of the FCOPY command permits the user to copy a le and its ACD, provided that the user is an owner or has RACD permission.
Listing ACDs Command Intrinsic LISTFILE SHOWDEV HPACDINFO HPACDPUT Purpose Show ACDs for les Show ACDs for devices Show ACDs for les and devices Show ACDs for les and devices Examples The LISTFILE command with option 4 shows the ACD status of a le in this fashion: LISTFILE FILEA,4 **************************** FILEA.XX.
The SHOWDEV command displays the ACD attributes of a device in this fashion: SHOWDEV 14;ACD LDEV AVAIL 14 OWNERSHIP VOLID DEN ASSOCIATION SPOOLED SPOOLER OUT ACD ENTRIES: @.@ : R,W,X This short program uses HPACDINDFO to retrieve the number of entries and rst user in the ACD of a le called TARGET: program acdinfo(input, output); type shortint = -32768..32767; var status filename numentry firstuser : : : : integer; packed array [1..28] of char; shortint; packed array [1..
Modifying ACDs Command Intrinsic ALTSEC HPACDPUT Purpose To change an ACD To change an ACD Adding ACD pairs To confer Read access on JOE.DESIGN for FILEA, enter this:. ALTSECT FILEA.XX.DESIGN;ADDPAIR=(R:JOE.DESIGN) Replacing ACDs To change the (previous) Read access for SAM.DOE to Write access enter this: ALTSECT FILEA.XX.DESIGN;REPPAIR(W:SAM.DOE) To assign Read and Write access to SAM.DOE, do this: ALTSEC FILEA.XX.DESIGN;REPPAIR(W,R:SAM.
Be aware that MPE/iX allows more user-mode pairs than MPE V/E does. You must have authorization to use the ;COPYACD parameter of the STORE and RESTORE commands. If you are not an owner of the le or do not have RACD permission, you get an error. The STORE command checks the ACD on disk for permission. RESTORE checks the ACD from the tape. For more details, refer to the MPE/iX Commands Reference Manual (32650-90003) and the MPE/iX Intrinsics Reference Manual (32650-90028).
Log of system logging con guration This log gives you an audit trail of changes to the logging con guration. This log is initially enabled (ON).
Log of printer access failure This log keeps track of failed attempts attaching spool les to printers. New spool les, which are logged by FOPEN as event #144, are not logged here. This log is initially disabled, but can be enabled by SYSGEN followed by a START command.
Log of stream initiation This log records the name of a streamed job, its number, the user that initiates it (and the logon), and the scheduled date and time. This log is initially disabled, but can be enabled by SYSGEN followed by a START command.
Log of user logging This log keeps a record of all OPENLOG and CLOSELOG intrinsic calls. The system manager can use it to see who accesses, or tries to access, the user logging facility. This log is initially disabled, but can be enabled by SYSGEN followed by a START command.
Log of process creation You can use this log to record all process creations. This log is initially disabled, but can be enabled by SYSGEN followed by a START command.
The input for these commands should be no longer than 80 characters. Default for all parameters is the wildcard @. For example, to select log records from log les 1 through 5, with log information about password changes (log type 134), and user identi cation JTEST,MARIA.PAYROLL, you would enter the following.
The information recorded in this logging includes header record type record length time stamp job or session number PIN Log information the identi cation of the user who changed a password: job or session name, user name, group name, and account name the identi cation of a user whose password was changed: user name, group name, and account name whenever the a ected password changes input logical device number from which the password was changed program le name from which password change was executed type ch
Table 13-1. Type 134 Record Format Length, Record Content in 16-bit words 1 1 1 3 2 8 8 8 1 1 25 3 8 8 8 8 Note record type (134) record length process identi cation number time stamp job type/job number target user name target group name target account name type changed input LDEV number executed from (reserved) user name group name account name job or session name The PASSWORD command, allows all users to change their own passwords.
the type of change to the ACD: create, add pair, replace pair, copy, delete pair, delete the program le name from which the ACD change was executed. status returned (HPE status) In this example, user JOHN.PAYROLL,DOE, with job or session name JREPORT, successfully created an ACD for a le called FTEST.TESTGP.PAYROLL, using the command executor. The LOGTOOL formats the following layout after the standard header: TARGET OBJECT: SOURCE OBJECT: FUNCTION: EXECUTED FROM: STATUS USER ACCOUNT: FTEST.TESTGP.
Traditional Mechanism for File Security The traditional security mechanism ( le access matrix and lockwords) associates with each account, group, and individual les a set of security provisions that speci es any restrictions on access to the les in that account or group, or to that particular le. Note These provisions apply to disk les only. If a le is protected by the traditional security mechanism and by an ACD de nition, the ACD de nition overrides the traditional security mechanism.
Table 13-3. Traditional File Access Mode Types DESCRIPTION ACCESS MODE :FILE PARAMETER Read-only IN Write-only OUT Write-SAVE OUTKEEP Append-only APPEND Read/Write INOUT Update UPDATE Permits le to be read but not written on. Used for device les, such as card reader and paper tape reader les, as well as magnetic tape, disk, and terminal output les. Permits le to be written on but not read. Any data already in the le is deleted when the le is opened.
Table 13-4. E ects of Access Modes CURRENT LOGICAL EOF RECORD POINTER ACCESS MODE Read-only Write-only Write-SAVE Append Read/Write Update 10 10 10 10 10 10 0 0 0 10 0 0 EOF AFTER OPEN 10 0 10 10 10 10 Consider a program that reads input from a terminal ( le name INDEV) directs output to a line printer (OUTDEV).
Table 13-5. User Type De nitions (Traditional Security) USER TYPE MNEMONIC MEANING CODE Any User ANY Account Librarian User AL Group Librarian User GL Creating User Group User CR GU Account Member AC Any user de ned in the system; this includes all categories de ned below. User with Account Librarian capability, who can manage certain les within his account that may or may not all belong to one group. User with Group Librarian capability, who can manage certain les within his home group.
At the account level, ve access modes are recognized: reading (R) appending (A) writing (W) locking (L) executing (X) Also at the account level, two user types are recognized: any user (ANY) account member (AC) Maintaining File Security 13-23
If no security provisions are explicitly speci ed for the account, the following provisions are assigned by default: For the system account (named SYS), through which the system manager user initially accesses the system, reading and executing access are permitted to all users; appending, writing, and locking access are limited to account members. Note Symbolically, these provisions are expressed as follows: (R,X:ANY;A,W,L:AC) In this format, colons are interpreted to mean, \ . . . is permitted only to .
For all other groups in the account, reading, appending, writing, saving, locking, and executing access are limited to group users. (R, A, W, L, X, S: GU). File-level security When a le is created, the security provisions that apply to it are the default provisions assigned by MPE/iX at the le level, coupled with the user-speci ed or default provisions assigned to the account and group to which the le belongs.
Table 13-6. Default Security Provisions (Traditional) FILEREFERENCE FILE ACCESS SAVE ACCESS TO GROUP PERMITTED lename.PUB.SYS Any le in public group of system account lename. groupname. Any le in any group SYS in system account Any le in public lename .PUB. accountname group of any account lename. groupname.
Suspending and restoring security provisions You may temporarily suspend the suspending and restoring security: lesj security restrictions on any disk le that you create. This allows the le to be accessed in any mode by any user; in other words, it o ers unlimited access to the le. You suspend the security provisions by entering the RELEASE command. (File lockword protection, however, is not removed by this command.
14 Getting File Information MPE/iX provides a number of commands and intrinsics that enable you to obtain information about your les. You can use the commands and intrinsics described in this chapter to obtain le information for a variety of purposes.
Displaying General File Information Some questions that you may wish to answer in this section include Does a le by this name exist in my account or group? How large is this le? When and by whom was this le created? What security provisions exist for this le? You can use this information in an interactive context, or you can use commands and intrinsics within an executing program to obtain and utilize the information. You use: LISTFILE LISTFILE ;TEMP LISTEQ ...
Specifying the list level If you do not indicate otherwise, LISTFILE displays only the unquali ed le name. You can optionally direct LISTFILE to display more detailed information about the le(s) that you specify, depending upon the parameter value that you specify in the command, as listed in Table 14-1. Option Name 02 ACD 01 LABEL 0 FILES 1 SUMMARY 2 DISC 3 DETAIL 4 SECURITY 5 DATA 6 QUALIFY 7 UNIQUE Table 14-1.
Specifying an alternate output le If you do not indicate otherwise, LISTFILE sends its output to $STDLIST. You can optionally specify a di erent output le to which the le descriptions are written. LISTFILE examples 1. List all les in your logon account and group with le names that contain the characters \INFO": LISTFILE @INFO@ INFOABST INFOUTLN INFOPREF PSMGINFO WINFOUTQ XLINFO 2. Show the le characteristics of all les with names beginning with \X" in a speci ed account and group: LISTFILE X@.INTRIN.
4. Obtain a detailed ACD report on a le: LISTFILE FILEA,-2 FILE = FILEA ************** ACD ENTRIES ************** SAM.DOE JOE.DOE @.DESIGN @.@ : : : : R W NONE X Displaying temporary le information with LISTFILE ... (;TEMP) The LISTFILE . . . (;TEMP) command is similar to LISTFILE, except that it displays information about the speci ed temporary les.
[:CMD] FINFO You can use the FINFO evaluator function interactively to retrieve information about a speci ed le. FINFO is a function of the expression evaluator, a system procedure used by the IF, WHILE, SETVAR, and CALC commands of the command interpreter. FINFO has two parameters. The rst is the le name of the le about which you wish to obtain information; this is a string, and must be either a fully or partially quali ed le name, or a FILE equation backreference.
CALC FINFO ('MYFILE',-13) 1029, $405, %2005 CALC FINFO ('MYFILE',-9) 0, $0, %0 FFILEINFO Use this intrinsic to retrieve information about a speci ed le. The le can be on any device, but it must be opened by the calling process at the time of the FFILEINFO call. If you wish to return label information from a le that is not opened, use FLABELINFO instead. FFILEINFO has one required parameter, lenum. This is the le number, which is returned when you open a le using FOPEN or HPFOPEN.
HPFOPEN(FILENUM,STATUS); FORMALDESIGNATOR:= EMPTYARRAY; FILECODE:=0; FOPTIONS:=0; CREATOR:=EMPTYARRAY; FGETINFO(FILENUM,FORMALDESIGNATOR,,FOPTIONS,,,,,FILECODE,,,,,,,,,,CREATOR); A complete description of the information that you can obtain using FGETINFO is given in the MPE/iX Intrinsics Reference Manual (32650-90028). FLABELINFO The FLABELINFO intrinsic returns information from the le label of a disk le. The le need not be opened at the time of the intrinsic call.
Determining Interactive/Duplicative Files with FRELATE This intrinsic is used for one speci c purpose: determining whether a pair of les (input le and list le) is interactive, duplicative, or both. Interactive means that the le requires human intervention for all input operations. For example, an input le and a list le opened to the same terminal would form an interactive pair. Duplicative means that all input to the input le is echoed automatically to the list le.
other type of le. The numrecs parameter returns the number of logical records in the bad block. You must use this intrinsic prior to calling FERRMSG, since the error code returned by FCHECK is used as a parameter in the call to FERRMSG. FERRMSG This intrinsic is used following a call to FCHECK, to return an error message explaining the nature of a le system error.
For les that are open when a CCG (EOF error) or CCL (irrecoverable le error) was returned, the le information display appears as shown in example 14-2. Example 14-2. File Information Display, Opened File +-F-I-L-E---I-N-F-O-R-M-A-T-I-O-N---D-I-S-P-L-A-Y+ ! FILE NAME IS TREEFILE.PSMG.
Line # 1 2,3 4,5 6,7 8 9 10 11 12 13 14 15 16 17 Table 14-3. PRINTFILEINFO Information Meaning The le name. The foptions in e ect. The aoptions in e ect. The device type and subtype, logical device number, (LDEV), device reference table (DRT), and unit of the device on which the le resides. If the le is a spool le, the ldev is the virtual rather than the physical device. The record and block size of the o ending record, in bytes and words, as noted.
A HP Pascal/XL Program Examples The HP Pascal/XL program examples in this appendix are provided to help you better understand how to use MPE/iX le system intrinsics to perform common le access tasks.
Program example A-1 This program illustrates how you can open three di erent les|an unlabeled magnetic tape le, $STDLIST, and a new disk le|and copy records sequentially from the tape le to the disk le while concurrently writing the records to $STDLIST. Program Algorithm The task speci ed above is accomplished by following the steps described below. Also indicated are the intrinsics used to accomplish le access tasks and the name of the procedure where the task is accomplished: 1.
Source code listing Example A-1.
procedure handle_file_error ( file_num : shortint; quit_num : shortint ); {************************************************************************} { procedure handle_file_error is invoked when a file system intrinsic } { returns and unsuccessful condition code. File information is printed } { to $STDLIST, then the program aborts.
begin file_name :='&tapefile&'; permanent := 3; update := 5; device_class := '&TAPE&'; density := 1600; HPFOPEN (file_num, status, formal_designator_option, file_name, domain_option, permanent, access_type_option, update device_class_option, device_class density_option, density ); if status.
begin ascii := 1; HPFOPEN (file_num, status, formal_designator_option, file_name, domain_option, domain, ascii_binary_option, ascii, access_type_option, access); if status.
until end_of_file; end; {end procedure } procedure close_file ( file_num : integer; disp : integer ); {************************************************************************} { procedure close_file is a generic file closing procedure that allows } { you to specify the final disposition of the file.
Program Example A-2 This Pascal/XL program example illustrates how you can use the HPFOPEN intrinsic to open a labeled magnetic tape le, then open a new disk le with a user-supplied name. After records are sequentially copied from the tape le to the disk le, both les are closed, the disk le is closed as a Permanent le.
Source code listing Example A-2.
procedure print_hpfopen_error ( error : status_type ) option inline; {************************************************************************} {* PURPOSE: *} {* This routine prints the status returned by HPFOPEN. *} {* PARAMETERS: *} {* error (input) *} {* - status returned by HPFOPEN *} {************************************************************************} begin {* print_hpfopen_error *} writeln ('HPFOPEN status = (info: ', error.info:1, '; subys: ', error.
procedure handle_file_error ( file_num : shortint; quit_num : shortint ); {************************************************************************} {* PURPOSE: *} {* This routine displays File System information about a file *} {* and then calls QUIT to terminate the program. *} {* PARAMETERS: *} {* file_num (input) *} {* - file number. The routine will print info about this *} {* file. *} {* quit_num (input) *} {* - quit number. This number will be displayed by QUIT when *} {* the program is terminated.
procedure open_tape_file ( var file_num : integer ); {************************************************************************} {* PURPOSE: *} {* This routine opens a labeled tape file.
if status.
procedure open_disk_file ( var file_num : integer ); {************************************************************************} {* PURPOSE: *} {* This routine prompts the user for a file name and opens a *} {* NEW disk file using the given name.
{* set up the remaining item values for the HPFOPEN intrinsic *} {**************************************************************} ascii := 1; update := 5; {* the disk file is to be an ASCII file *} {* update access will be used to write to the disk file*} HPFOPEN (file_num, status, formal_designator_option, file_name, ascii_binary_option, ascii, access_type_option, update); if status.
procedure copy_file_from_tape_to_disk ( tape_file : integer; disk_file : integer ); {************************************************************************} {* PURPOSE: *} {* This routine copies a tape file to a disk file one record at *} {* a time (sequential access).
handle_file_error (disk_file, 5); end; end; until end_of_file; end; {* copy_file_from_tape_to_disk *} HP Pascal/XL Program Examples A-17
procedure close_tape_file ( file_num : integer ); {************************************************************************} {* PURPOSE: *} {* This routine closes the tape file.
else file_closed := true; until file_closed; end; { close_disk_file HP Pascal/XL Program Examples } A-19
{************************************************************************} { MAIN PROGRAM } {************************************************************************} begin open_tape_file (tape_file); { STEP open_disk_file (disk_file); { STEP print_user_label (tape_file); { STEP copy_file_from_tape_to_disk (tape_file, disk_file); { STEP close_tape_file (tape_file); { STEP close_disk_file (disk_file); { STEP end.
Program Example A-3 This HP Pascal/XL program illustrates how you can use a sequential method of reading records from an old disk le and use a random access method of writing the records in an inverted order to a new user-labeled disk le, where record 1 of the rst le is written to location n of the second le, record 2 is written to location n-1, and so on. Program Algorithm The task speci ed above is accomplished by following the steps described below.
Source code listing Example A-3.
procedure handle_file_error ( file_num : shortint; quit_num : shortint ); {***********************************************************************} { procedure handle_file_error prints file information on the job/session} { list device, then aborts the program.
if status.
procedure write_user_label ( file_num : integer; buffer : pac80; length : integer; lnum : integer ); {************************************************************************} { procedure write_user_label writes a user-defined label to the specified} { file.
handle_file_error (old_discfile, 4) else if ccode = ccg then end_of_file := true else A-26 HP Pascal/XL Program Examples
begin rec := rec - 1; { decrement record pointer FWRITEDIR (new_discfile, inbuf, 128, rec); if ccode <> cce then handle_file_error (new_discfile, 5); end until end_of_file { check control variable EOF end; { end copy_oldfile_to_newfile } } } procedure close_disk_file ( file_num : integer; disp : integer ); {************************************************************************} { procedure close_disk_file is a disk file closing procedure that allowsa } { you to specify the final disposition of the file
Program Example A-4 This HP Pascal/XL program illustrates how you can use the FREADSEEK intrinsic to improve I/O performance during random access reads. The program opens a permanent disk le containing data, and $STDLIST. Even numbered records are read from the data le and printed to $STDLIST. Program Algorithm The task speci ed above is accomplished by following the steps described below.
Source code listing Example A-4. Random Access program Read_Example (input,output); {************************************************************************} { DECLARATION PART } {************************************************************************} const CCG = 0; { condition code warning CCL = 1; { condition code error CCE = 2; { condition code successful type file_name = packed array [1..9] of char; buffertype = packed array [1..
procedure open_files; {************************************************************************} { procedure open_files opens the data file and $STDLIST using the FOPEN } { intrinsic.
procedure read_from_datafile; {************************************************************************} { procedure read_from_data_file first calls procedure read_user_label to } { print the label to $STDLIST, then enters a loop to select only even } { numbered records from the data file and writing them to $STDLIST.
begin open_files; read_user_label; read_from_datafile; close_files; { { { { end.
Program Example A-5 This HP Pascal/XL program example illustrates how you can update a particular record of a shared data le. In addition, this program example uses le system locking intrinsics (FLOCK, FUNLOCK) to ensure exclusive access to the le while the update occurs. Program Algorithm The task speci ed above is accomplished by following the steps described below. Also indicated are the intrinsics used to accomplish le access tasks and the name of the procedure where the task is accomplished: 1.
Source code listing Example A-5.
procedure FUPDATE; intrinsic; procedure QUIT; intrinsic; { update record { use in error handler HP Pascal/XL Program Examples } } A-35
procedure handle_file_error ( file_num : shortint; quit_num : shortint ); {************************************************************************} { procedure handle_file_errorPrints the file information on the } { session/job list device.
access_type_option, access, exclusive_option, excl dynamic_locking_option, lockable); if status.
end; { end open_file } procedure update_file ( old_discfile : integer ); {************************************************************************} { procedure update_file pdates records in the disk file with the } { replacement read from the stdin. } *************************************************************************} var dummy inbuf end_of_file read_length : : : : integer; array [1..
end; handle_file_error (file_num, 2); { end update_file HP Pascal/XL Program Examples } A-39
procedure close_disk_file ( file_num : integer; disp : integer ); {*************************************************************************} {procedure close_disk_file is a generic file closing procedure that } {allows you to specify the final disposition of the file you are closing.
Index 1 1090 A le code, 2-40 aborting NOWAIT I/O, 2-2 access exclusive, 12-2 modes, 13-19 multi , 12-1{5 random, 8-1{3, 9-1, 9-3{4 restricting, 13-19 restricting by type, 13-21 restricting by user, 13-21 semi-exclusive, 12-3 sequential, 8-1{3, 9-1, 9-2{3 shared, 12-3 simultaneous, 12-1 access control de nitions (ACD), 13-1{18 accessing les, 2-1, 2-19, 2-22 les, remote, 3-11 account security, 13-22 ACD adding, 13-8 changes, logging, 13-17 commands related to, 13-3, 13-4 copying, 13-7 creating, 13-4 dele
creating ACDs, 13-4 les, 2-1 D data elements, 1-1 data transfer, 1-1, 7-1{8 intrinsics, 7-3 multiple records, 7-5 default record size les, 2-33 line printer les, 2-33 magnetic tape les, 2-33 plotter les, 2-33 programmable controller les, 2-33 synchronous single-line controller les, 2-33 terminal les, 2-33 de ning le characteristics, 2-1, 2-19 deleting ACDs, 13-8 les, 4-3 device les, 1-3, 5-11 jobs and, 1-3 opening, 5-10 sessions and, 1-3 device owners acds, 13-2 devices ASCII transmission, 2-41 binary tra
altering use, 2-1 ASCII, 2-32, 2-41 attributes, 2-1 backreferencing, 3-4 binary, 2-32, 2-41 changing security, 13-26 characteristics, 2-22 circular, 2-31 closing, 6-1{6 closing as permanent, 6-2 compatibility (pre- and post-900 series), 2-32{33 creating, 2-1, 3-3 creating with BUILD, 2-21 creating with FOPEN, 2-19 creating with HPFOPEN, 2-1 default record sizes, 2-33 de ning characteristics, 2-1, 2-19 deleting, 4-3 designators, 3-1{12 device-dependent characteristics, 5-10 devices, 1-3, 5-11 devices, openin
variable-length, 2-26, 2-28 FPARSE intrinsic, 3-11 FPOINT intrinsic, 7-6 FREADDIR intrinsic, 7-3, 9-3, 9-4 FREAD intrinsic, 2-2, 7-3, 9-2, 9-4 NOWAIT I/O, 2-2 FREADSEEK intrinsic, 9-4 FRELATE intrinsic, 3-7, 14-9 FSPACE intrinsic, 7-6 function FINFO, 14-6 FUNLOCK intrinsic, 10-1, 12-5 FUPDATE intrinsic, 7-3, 10-1 FWRITE intrinsic, 2-2, 7-3, 8-4 NOWAIT I/O, 2-2 FWRITELABEL intrinsic, 8-8 G getting le information, 14-1{12 global multi access, 12-4 group security, 13-24 H half-word boundaries les, 2-32
les, 4-4 lockwords changing, 3-4 les, 3-3{4 removing, 3-4 LOG le code, 2-40 log les DISC= parameter and, 2-40 specifying number of records, 2-40 logging ACD changes, 13-17 le security events, 13-15 password changes, 13-15 printer access failure, 13-11 process creation, 13-14 restores, 13-10 stream initiation, 13-12 system events, 13-9 system logging con guration, 13-10 user, 13-14 user logging, 13-13 long-mapped access, 11-3 N M versus old le, 3-10 opening device les, 5-10 les, 5-1{15 les, mapped, 11-3 $
P pairs ACDs, 13-2 parsing le designators, 3-11{12 passed les, 3-7{10 passwords changes, logging, 13-15 peripheral devices, 1-1 les, 1-2, 1-3, 2-26 permanent les closing, 6-4 devices, 5-11 domains, 4-2 le domain, 4-2 plotter les default record size, 2-33 pointing to a record, 7-6 prede ned les, 3-4 preserving ACDs, 13-4 printer access failure, logging, 13-11 PRINTFILEINFO intrinsic, 14-10 PRINT intrinsic, 8-4 PRINTOP intrinsic, 8-5 PRINTOPREPLY intrinsic, 8-5 procedure le system error check, 14-12 process
device les and, 1-3 sets input, 3-6{7 output, 3-6{7 volume, 2-34 SETVAR command, 3-10 shared access, 12-3 devices, 2-1, 2-19 les, 1-3 sharing les, 12-1{5 hazards, 12-5 restrictions, 12-1 short-mapped access, 11-2 specifying disk volume restrictions, 2-34 le codes, 2-34{40 le types, 2-30{31 record format, 2-26 record size, 2-32{33 storage format, 2-41 specifying le domain, 4-1{4 spooled devices, 1-3 spooling console operator, 1-3 user, 1-3 standard les, 2-30 input les, 3-5 output les, 3-5 $STDIN, 3-5, 3-6 op
