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

READ

In this article, we finish our look at file I/O in UCL. This time, we will look at the READ command. Here is the user documentation:

READ

Reads a single record from the specified file and places the data in the specified symbol. If the input file is sequential or untyped, a single line is read.

Format

READ file{:} symbol

Parameters

file
This is the symbol name used when the file was opened. The logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND can also be used. The colon suffix is optional.

symbol
This is the symbol to write the data to.

Description

To read a file, it must first be opened with the OPEN command (except for the process-permanent logicals SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR).
Unlike the INQUIRE command, the READ command doesn't trim extra whitespace, remove quotation marks, or change case. Nor does READ do symbol subsitution.
After reading from a file, the file position is moved to the next location such that the next READ will return the next line or record in the file.

Qualifiers

/DELETE
Deletes the record from an indexed file after it has been read.

/END_OF_FILE=label
If the file position is at the end of the file, and this qualifier is specified, control is transferred to the specified label.

/ERROR=label
If the file read causes an error, control is transferred to the specified label.

/INDEX=n
Specifies the index (n) to look up when reading an indexed file. This has no effect on non-indexed files. If /INDEX is not specified for an indexed file, the last index read is used (if this is the first read after opening an indexed file, index 0 is used).

/KEY=string
Reads the first record with the key that matches the specified string. Binary and integer keys are not allowed. This applies only to indexed files.

/MATCH=comparison
Specifies the algorithm for matching keys. This must be one of the following values:
Comparison ValueMeaning
EQSelects keys that equal the match value (default)
GESelects keys greater than or equal to the match value
GTSelects keys greater than the match value
LESelects keys less than or equal to the match value
LTSelects keys less than the match value

/NOLOCK
Indicates that the read record is not to be locked.

/PROMPT=string
Indicates a prompt to display when reading from a terminal. The default prompt is "DATA:".

/TIME_OUT=n
Indicates the number of seconds until the READ operation is terminated if no data is received.

/NOTIME_OUT (default)
Indicates that there is no timeout when waiting for data.

/WAIT
Indicates to wait for a record to become available.

Example


$ OPEN/READ IN Filename
$Loop:
$ READ/END_OF_FILE=Done IN Text
$ WRITE SYS$OUTPUT Text
$ GOTO Loop
$Done:
$ CLOSE IN


                    if( Sym = 'read' ) then
                    begin
                        Process_Read ;
                    end else
This code is added to the Process routine. 

procedure Process_Read ;

var _Delete, _Wait : boolean ;
    I : integer ;
    I64, Idx : int64 ;
    F : TCOM_File64 ;
    EOF, Error, Index, Key, Match, Prompt, S, Sym, Timeout, Parameter : string ;
    P : PAnsiChar ;
    Res : int64 ;
    Status : int64 ;
    Switches : TStringList ;

begin
    // Process switches...
    _Wait := False ;
    Prompt := 'DATA:' ;
    Switches := Parse_Switches ;
    for I := 0 to Switches.Count - 1 do
    begin
        S := lowercase( Switches[ I ] ) ;
        Parameter := '' ;
        if( Switch_Match( S, 'delete', 1, Parameter ) ) then
        begin
            _Delete := True ;
            if( Parameter <> '' ) then
            begin
                Exception( UCL_NOVALU, S ) ;
                Switches.Free ;
                exit ;
            end ;
        end else
        if( Switch_Match( S, 'end_of_file', 2, EOF ) ) then
        begin
        end else
        if( Switch_Match( S, 'error', 2, Error ) ) then
        begin
        end else
        if( Switch_Match( S, 'index', 1, Index ) ) then
        begin
        end else
        if( Switch_Match( S, 'key', 1, Key ) ) then
        begin
        end else
        if( Switch_Match( S, 'match', 1, Match ) ) then
        begin
            if(
                ( Match <> 'gt' )
                and
                ( Match <> 'ge' )
                and
                ( Match <> 'le' )
                and
                ( Match <> 'lt' )
                and
                ( Match <> 'eq' )
              ) then
            begin
                Exception( UCL_NOVALU, Match ) ;
                Switches.Free ;
                exit ;
            end ;
        end else
        if( Switch_Match( S, 'nolock', 3, Parameter ) ) then
        begin
            if( Parameter <> '' ) then
            begin
                Exception( UCL_NOVALU, S ) ;
                Switches.Free ;
                exit ;
            end ;
        end else
        if( Switch_Match( S, 'prompt', 3, Prompt ) ) then
        begin
        end else
        if( Switch_Match( S, 'time_out', 1, Timeout ) ) then
        begin
        end else
        if( Switch_Match( S, 'notime_out', 3, Parameter ) ) then
        begin
            Timeout := '' ;
            if( Parameter <> '' ) then
            begin
                Exception( UCL_NOVALU, S ) ;
                Switches.Free ;
                exit ;
            end ;
        end else
        if( Switch_Match( S, 'wait', 1, Parameter ) ) then
        begin
            _Wait := True ;
            if( Parameter <> '' ) then
            begin
                Exception( UCL_NOVALU, S ) ;
                Switches.Free ;
                exit ;
            end ;
        end else
        begin
            Exception( UCL_IVQUAL, S ) ;
            Switches.Free ;
            exit ;
        end ;
    end ;
    Switches.Free ;
This new function handles the READ command. First, we process the switches. 

    // Get symbol name (file)...
    Sym := trim( Get_Token ) ;
    if( length( Sym ) = 0 ) then
    begin
        Sym := lowercase( Get_Prompted_Parameter( '_Log name: ' ) ) ;
        if( Sym = '' ) then
        begin
            exit ; // Aborted
        end ;
    end ;
    if( Parser.Peek = ':' ) then
    begin
        Get_Token ; // Eat the colon
    end ;

    // Get file...
    Sym := LIB_Get_Symbol( Sym ) ;
    if( trim( Sym ) = '' ) then
    begin
        Exception( UCL_NULFIL ) ;
        exit ;
    end ;
    if( not Valid_Int( Sym, I64 ) ) then
    begin
        Exception( UCL_UNDSYM, '' ) ;
        exit ;
    end ;
    Idx := File_Handles.Indexof( pointer( I64 ) ) ;
    if( Idx = -1 ) then // Not a file handle
    begin
        Exception( UCL_UNDSYM, '' ) ;
        exit ;
    end ;
    F := TCOM_File64( File_Handles[ Idx ] ) ;
Now we get the file's symbol name, then get the symbol's value and verify that it is in the file handle list. Of course, we exit if there was an error. Then we get the file instance. 

    // Get symbol name...
    Sym := trim( Get_Token ) ;
    if( length( Sym ) = 0 ) then
    begin
        Sym := lowercase( Get_Prompted_Parameter( '_Symbol: ' ) ) ;
        if( Sym = '' ) then
        begin
            exit ; // Aborted
        end ;
    end ;

    // Prompt...
    if( Prompt <> '' ) then
    begin
        if( F.Interactive ) then
        begin
            F.Blockwrite( PChar( S )[ 0 ], length( S ), Res ) ;
        end ;
    end ;
Next we get the symbol that we will write the data into. Then, unless a null prompt was specified, we write the prompt to the file if the file is an interactive device. 

    if( F.EOF ) then
    begin
        if( EOF <> '' ) then
        begin
            Parser.Put_Token( 'goto ' + EOF ) ;
            exit ;
        end ;
    end ;
Now we check to see if we're at the end of the file. If so, and /END_OF_FILE is specified, we put the goto command into the parser and exit so that we jump to the indicated label. 

    F.Readln( P ) ;
    Status := LIB_Get_Exception( 0 ) ;
    if( Status <> 0 ) then // Read error
    begin
        if( Error <> '' ) then
        begin
            Parser.Put_Token( 'goto ' + Error ) ;
        end else
        begin
            S := LIB_Get_Exception_Text( 0, Status ) ;
            Set_Exception( S ) ;
        end ;
        exit ;
    end ;
    S := string( P ) ;
    LIB_Set_Symbol( Sym, S ) ;
    Status := LIB_Get_Exception( 0 ) ;
    if( Status <> 0 ) then
    begin
        S := LIB_Get_Exception_Text( 0, Status ) ;
        Set_Exception( S ) ;
    end ;
end ; // Process_Read
Finally, we read the file. If there was an exception, we jump to the specified error label (if defined) or else set the error. Then we write the value to the specified symbol, checking for an exception on that operation. Note that we do not use the /ERROR setting for this final exception check since /ERROR is only for the READ operation itself.

In the next article, we will look at the next UCL feature.

 

Copyright © 2021 by Alan Conroy. This article may be copied in whole or in part as long as this copyright is included.