|
1 Introduction 2 Ground Rules Building a File System 3 File Systems 4 File Content Data Structure 5 Allocation Cluster Manager 6 Exceptions and Emancipation 7 Base Classes, Testing, and More 8 File Meta Data 9 Native File Class 10 Our File System 11 Allocation Table 12 File System Support Code 13 Initializing the File System 14 Contiguous Files 15 Rebuilding the File System 16 Native File System Support Methods 17 Lookups, Wildcards, and Unicode, Oh My 18 Finishing the File System Class The Init Program 19 Hardware Abstraction and UOS Architecture 20 Init Command Mode 21 Using Our File System 22 Hardware and Device Lists 23 Fun with Stores: Partitions 24 Fun with Stores: RAID 25 Fun with Stores: RAM Disks 26 Init wrap-up The Executive 27 Overview of The Executive 28 Starting the Kernel 29 The Kernel 30 Making a Store Bootable 31 The MMC 32 The HMC 33 Loading the components 34 Using the File Processor 35 Symbols and the SSC 36 The File Processor and Device Management 37 The File Processor and File System Management 38 Finishing Executive Startup Users and Security 39 Introduction to Users and Security 40 More Fun With Stores: File Heaps 41 File Heaps, part 2 42 SysUAF 43 TUser 44 SysUAF API Terminal I/O 45 Shells and UCL 46 UOS API, the Application Side 47 UOS API, the Executive Side 48 I/O Devices 49 Streams 50 Terminal Output Filters 51 The TTerminal Class 52 Handles 53 Putting it All Together 54 Getting Terminal Input 55 QIO 56 Cooking Terminal Input 57 Putting it all together, part 2 58 Quotas and I/O UCL 59 UCL Basics 60 Symbol Substitution 61 Command execution 62 Command execution, part 2 63 Command Abbreviation 64 ASTs 65 Expressions, Part 1 66 Expressions, Part 2: Support code 67 Expressions, part 3: Parsing 68 SYS_GETJPIW and SYS_TRNLNM 69 Expressions, part 4: Evaluation UCL Lexical Functions 70 PROCESS_SCAN 71 PROCESS_SCAN, Part 2 72 TProcess updates 73 Unicode revisted 74 Lexical functions: F$CONTEXT 75 Lexical functions: F$PID 76 Lexical Functions: F$CUNITS 77 Lexical Functions: F$CVSI and F$CVUI 78 UOS Date and Time Formatting 79 Lexical Functions: F$CVTIME 80 LIB_CVTIME 81 Date/Time Contexts 82 SYS_GETTIM, LIB_Get_Timestamp, SYS_ASCTIM, and LIB_SYS_ASCTIM 83 Lexical Functions: F$DELTA_TIME 84 Lexical functions: F$DEVICE 85 SYS_DEVICE_SCAN 86 Lexical functions: F$DIRECTORY 87 Lexical functions: F$EDIT and F$ELEMENT 88 Lexical functions: F$ENVIRONMENT 89 SYS_GETUAI 90 Lexical functions: F$EXTRACT and F$IDENTIFIER 91 LIB_FAO and LIB_FAOL 92 LIB_FAO and LIB_FAOL, part 2 93 Lexical functions: F$FAO 94 File Processing Structures 95 Lexical functions: F$FILE_ATTRIBUTES 96 SYS_DISPLAY 97 Lexical functions: F$GETDVI 98 Parse_GetDVI 99 GetDVI 100 GetDVI, part 2 101 GetDVI, part 3 102 Lexical functions: F$GETJPI 103 GETJPI 104 Lexical functions: F$GETSYI 105 GETSYI 106 Lexical functions: F$INTEGER, F$LENGTH, F$LOCATE, and F$MATCH_WILD 107 Lexical function: F$PARSE 108 FILESCAN 109 SYS_PARSE 110 Lexical Functions: F$MODE, F$PRIVILEGE, and F$PROCESS 111 File Lookup Service 112 Lexical Functions: F$SEARCH 113 SYS_SEARCH 114 F$SETPRV and SYS_SETPRV 115 Lexical Functions: F$STRING, F$TIME, and F$TYPE 116 More on symbols 117 Lexical Functions: F$TRNLNM 118 SYS_TRNLNM, Part 2 119 Lexical functions: F$UNIQUE, F$USER, and F$VERIFY 120 Lexical functions: F$MESSAGE 121 TUOS_File_Wrapper 122 OPEN, CLOSE, and READ system services UCL Commands 123 WRITE 124 Symbol assignment 125 The @ command 126 @ and EXIT 127 CRELNT system service 128 DELLNT system service 129 IF...THEN...ELSE 130 Comments, labels, and GOTO 131 GOSUB and RETURN 132 CALL, SUBROUTINE, and ENDSUBROUTINE 133 ON, SET {NO}ON, and error handling 134 INQUIRE 135 SYS_WRITE Service 136 OPEN 137 CLOSE 138 DELLNM system service 139 READ 140 Command Recall 141 RECALL 142 RUN 143 LIB_RUN 144 The Data Stream Interface 145 Preparing for execution 146 EOJ and LOGOUT 147 SYS_DELPROC and LIB_GET_FOREIGN CUSPs and utilities 148 The I/O Queue 149 Timers 150 Logging in, part one 151 Logging in, part 2 152 System configuration 153 SET NODE utility 154 UUI 155 SETTERM utility 156 SETTERM utility, part 2 157 SETTERM utility, part 3 158 AUTHORIZE utility 159 AUTHORIZE utility, UI 160 AUTHORIZE utility, Access Restrictions 161 AUTHORIZE utility, Part 4 162 AUTHORIZE utility, Reporting 163 AUTHORIZE utility, Part 6 164 Authentication 165 Hashlib 166 Authenticate, Part 7 167 Logging in, part 3 168 DAY_OF_WEEK, CVT_FROM_INTERNAL_TIME, and SPAWN 169 DAY_OF_WEEK and CVT_FROM_INTERNAL_TIME 170 LIB_SPAWN 171 CREPRC 172 CREPRC, Part 2 173 COPY 174 COPY, part 2 175 COPY, part 3 176 COPY, part 4 177 LIB_Get_Default_File_Protection and LIB_Substitute_Wildcards 178 CREATESTREAM, STREAMNAME, and Set_Contiguous 179 Help Files 180 LBR Services 181 LBR Services, Part 2 182 LIBRARY utility 183 LIBRARY utility, Part 2 184 FS Services 185 FS Services, Part 2 186 Implementing Help 187 HELP 188 HELP, Part 2 189 DMG_Get_Key and LIB_Put_Formatted_Output 190 LIBRARY utility, Part 3 191 Shutting Down UOS 192 SHUTDOWN 193 WAIT 194 SETIMR 195 WAITFR and Scheduling 196 REPLY, OPCOM, and Mailboxes 197 REPLY utility 198 Mailboxes 199 BRKTHRU 200 OPCOM 201 Mailbox Services 202 Mailboxes, Part 2 203 DEFINE 204 CRELNM 205 DISABLE 206 STOP 207 OPCCRASH and SHUTDOWN 208 APPEND Glossary/Index Downloads |
Help Files There is one last topic we need to address before we can consider our coverage of system configuration to be complete. This topic is user help. Unix/Linux has the man utility and Windows has had various help systems over time (.hlp, .chm, etc). Likewise, VMS also has a help facility for the same purpose - to provide documentation for the user. There are three aspects to this: the HELP CUSP, the help files, and the help services. We will cover the HELP CUSP in a future article. The help service is used by CUSPs and utilities to display in-program help. The help files are the containers of the actual help text. Why do we need to address this now? Because the CUSPs we've been covering need to support in-program help, our discussion of them isn't complete until we have implemented help for them. First, let's talk about library files. Library files contain multiple descrete named chunks of data, which we call "modules". There are various kinds of library files. Some contain code that is linked into programs during compilation/linking. This code is stored in the library file as modules that are object files. Note that shared librarys (such as Windows DLLs) are actually a form of executable files and don't fit into our current discussion of library files. Text libraries are a type of library that contain named text "articles". In the case of Help libraries, these articles are help topics. When requested, the textual data can be retrieved from the file and shown to the user. These help modules can refer to other help modules by name which creates a hierarchical structure to allow the user to see related information or drill down into more detailed information, if desired (modules in object files can also refer to other modules by name, so this is nothing unique to text libraries in general, or help libraries in specific). Another feature of all library files is that entries can be added, removed, renamed, updated, and retrieved. So, what kind of file structure could we use to support libraries? One idea would be a relational database system - and that is a fine solution. However, that might be a bit of overkill since we only need the most basic database features, plus we haven't covered any kind of database, per se, so far in these articles. But we have discussed another file layout that would serve our purposes very well: file systems. Essentially, any named entry in a library file is equivalent to a named file. The directory structure nicely fits the need for storing auxillary data along with the entry files. And that is, in fact, what we will use (VMS uses a separate file format for library files, but like UOS, the same format is used for all types of libraries). A library file is a file system container that can store named entries as files, and auxillary information in files in a separate directory in the library file or as properties (ancillary data streams) for the files inside the file system container file. One could theoretically store any number of different kinds of entries in a single file, if so desired. Though we will be keeping the different kinds of libraries segregated by type of data, there is nothing to prevent a user from storing help articles, object code, and audio media all in the same library file. Note that VMS libraries can only contain a single type of data, so UOS is more flexible in that respect. The program that allows us to manage a library is called the LIBRARIAN. It uses library routines to perform the various options on a library file, and those routines are also used by programs which wish to read help articles for display to the user. So, the next few articles will first address the library routines, then the LIBRARIAN utility, and then we'll revisit the CUSPs we've already covered to add help support to them. Now that we've discussed libraries in general, let's look at help libraries specifically. The root directory of the library file will contain a "help" folder within which the help articles will be stored. Each article will cover a single topic of help. In VMS, these articles were plain text, with a special symbol to indicate sub-topics. In UOS, the articles are simple HTML, with anchor tags (<a>) being used to link to other topics. The way we display HTML text will vary from device to device. For instance, on a dumb terminal, we would simply write a plain text version; on a electrostatic printer (such as a copier/printer), we'd use postscript to format things; and on a PC screen, we'd display it in a manner similar to an internet web browser. These details are things we will handle in a future article. For now, we'll just convert the HTML to plain text. Help libraries have the default extension of .HLB, and the input source file default extension is .HLP. The use of HTML means that the help layout is quite different from VMS help modules. On a character-cell terminals, the output of help via the LBR_Output_Help service will resemble what the user sees on VMS, but the output is constructed from the HTML text in this way: the HTML text is converted to plain-text and all anchor tags are used to build a list of related topics at the end of the text. Anchor tags refer to other modules, by name, in the help library. An anchor tag can refer to "." for the current module, or ".." to indicate backing up to the previously displayed module in the interactive help session. One other difference from VMS is that the main (root) help module (article) is the module named "Index". If this module does not exist, and the root module is needed, the result will likely be an error. The Librarian services herein vary somewhat from VMS. Though we try to stick to the VMS documentation, the way help libraries differ between UOS and VMS is such that some changes were required, while other changes were made to simplify things. Although we could have slavishly followed the VMS documentation more closely, it would have made things more complicated than necessary - especially given the inherent differences in the library file formats. For example, services that return help text return it one line at a time on VMS, but the entire module text is returned at a time on UOS. This is to support future GUI display of HTML. One final note about the differences between UOS and VMS: VMS help files are assumed to be designed hierarchically. That is, each topic reference in a help article is considered to be a sub-topic of that article. UOS makes no such assumption - links can be to "child" topics, like VMS, or to "sibling" topics, or "parent" topics, or any topic. So there is no inherent child/parent relationship as is implied in VMS. In VMS, one backs up to a topic higher in the tree, where as in UOS, one merely backs up to the previously viewed topic. Of course, a UOS help library could be organized like VMS if desired, but none of the help officially provided with UOS will have that restrictive design. Now let's look at the user documentation for the librarian service routines. Note that we are only going to address the routines that apply to help libraries at this time. We'll cover other librarian services in future articles. All librarian service routine names are prefixed with "LBR_". To create a new library or use an existing library, the LBR_INI_CONTROL routine must be called to obtain a context number. This is passed to the other LBR_ routines and allows multiple libraries to be accessed without having to close one to open a new one. LBR_Open is then used to open a library file. LBR_Close is used to close a library file when you are finished with it. LBR_OUTPUT_HELP can be used to display help to the user and query him for more information, without the need to use LBR_INI_CONTROL, LBR_OPEN, or LBR_CLOSE.
LBR_Close Format: LBR_Close context Returns: Returns a condition code. Argument: context
Description Closes a library file opened with LBR_OPEN. This should always be called when you are finished with a library file. Condition Codes Returned: LBR_ILLCTL Specified context is not valid.
LBR_Delete Format: LBR_Delete context name Returns: Returns a condition code. Arguments: context
name
Description Deletes the specified module from the library. Condition Codes Returned: LBR_ILLCTL Specified context is not valid.
LBR_Get_Help Format: LBR_Get_Help context {line_width} {routine} {data} {key} Returns: Returns a condition code. Arguments: context
line_width
routine
data
key
Description Returns the specified help module text. Note that most application programs use LBR_OUTPUT_HELP to display help. Condition Codes Returned: LBR_ILLCTL Specified context is not valid.
LBR_Ini_Control Format: LBR_Ini_Control context function {type} {name} {default} {result} {length} Returns: Returns a condition code. Arguments: context
function
type
name
default
result
length
Description LBR_Ini_Control must be called before any other LBR_ service, except for LBR_OUTPUT_HELP. After calling, the LBR_OPEN service must be used to open or create the library. When done, the library should be closed with LBR_Close. If the call fails, the returned context is 0 and the service returns a condition code indicating the problem. Otherwise, the returned context is the value that must be used for other LBR_ calls. Condition Codes Returned: LBR_ILLFUNC Requested function is not valid.
LBR_Open Format: LBR_Open context {options} {name} Returns: Returns a condition code. Arguments: context
options
name
Description The LBR_OPEN service must be used to open or create a library. When done, the library should be closed with LBR_Close. Condition Codes Returned: LBR_ILLCTL Specified library control index is not valid.
LBR_Output_Help Format: LBR_Output_Help routine {width} {path} {library} {flags} {input} Returns: Returns a condition code. Arguments: routine
width
path
library
flags
input
Description LBR_Output_Help is used to display help text. A program can leave the entire processing of help to the service by providing no routine or input arguments and specifying HLP_M_PROMPT in the flags. LBR_INI_CONTROL, LBR_OPEN, and LBR_CLOSE are all handled internally. Condition Codes Returned: LBR_ILLINROU Input routine improperly specified or omitted.
LBR_Put_Module Format: LBR_Put_Module context name module Returns: Returns a condition code. Arguments: context
name
module
Description LBR_Put_Module writes a memory image of a module to the library. Condition Codes Returned: LBR_ILLCTL Specified library control index is not valid. In the next article, we will begin to look at the code to implement the above library services. |