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

Symbol assignment

We've talked about symbols and assigning values to them in past articles, but in this article, we will cover the code that implements the mechanism of symbol assignment. Note: there are more differences in DCL than in UCL due to the lack of type checking in UCL. Here's the documentation:

= (Assignment)

This assigns a value to a symbol.

Format
symbol{[position,size]} {:}={=} value

Description

UCL has two symbol scopes: local and global. The local symbols are stored in the process symbol table and the global symbols are stored in the job symbol table. For the root process in a process tree (the job process), these symbols are the same. For subprocesses, the local symbols are different than the global symbols When one is referenced, the local symbol will be used if it exists. If not found, the global symbol is used. The symbol need not be defined when a value is assigned to it. If it doesn't exist, it will be created. The use of the = (single equal) will assign a value to a local symbol, whereas the == (double equal) will assign the value to a global symbol.

If the equals is prefixed with a colon (:), the value being assigned to the symbol is assumed to be a string - otherwise if it can be interpreted as an integer value, it is converted to normalized decimal form before the symbol is set. That is, any leading "0"s are removed and any hex values (specified with "%X") are converted to decimal.

When using the string assignment (:= or :==), you can also specify a substring to set within the existing symbol. The format is:

symbol[offset,length] := value

where "symbol" is the symbol's name, "offset" is the starting offset (0 = first character), and "length" is the number of characters to replace in the symbol's value. Negative values are not allowed for the offset or length. A length of 0 will result in no change to the symbol. In fact, if the symbol doesn't exist, assigning a substring with a length of 0 will not result in the symbol being created - it is a null operation. If the offset plus the length is greater than the length of the symbol's existing value, that value will be extended with space characters to be the necessary width. Likewise, if the specified length is less than the length of the value being assigned, the assigned value is space-filled at the end to be the appropriate length. If the length is less than the length of the assigned value, only the specified number of bytes are copied to the symbol.

The following table illustrates the different assignment operators.
OperatorLocal/GlobalExampleResulting symbol value
=LocalA="01234"1234
==GlobalA=="01234"1234
:=LocalA:="01234"01234
:==GlobalA:=="01234"01234

Examples


X = "Text"
Assigns the local symbol X. 

X == "Global text"
Assigns the global symbol X. 

$ X = "3"
The local symbol X is set to "3".

$ X[3,1] := "0"
The existing local symbol X is set to "3  0".

$ X[2,3] := "ABCD"
The local symbol X is now "3 ABC". Note that only "ABC" is copied into X because the specified length is 3. The second space and "0" previously existing in X are overwritten with "AB", and the length of X is expanded to include "C".

                if( S = '[' ) then
                begin
                    Process_SubRange_Assignment( Sym ) ;
                end else
                if( ( S = '=' ) or ( S = '==' ) or ( S = ':=' ) or ( S = ':==' ) ) then
                begin
                    Process_Assignment( Sym, S ) ;
                end else
We modify the Process routine to handle the normal and substring assignments. 

procedure Process_Assignment( const Sym, S : string ;
    P : integer = -1 ; L : integer = -1 ) ;

var Context : string ;
    Err, Status : integer ;
    Table : integer ;
    Work : string ;

begin
    if( copy( S, 1, 1 ) = ':' ) then // String assignment
    begin
        Work := Get_Expression( Err, Context ) ;
        if( Err <> 0 ) then
        begin
            Parser.Grab_Line ; // Ignore rest of the line
            Set_Exception( UCL_ERT( Err ), Context ) ;
            exit ;
        end ;
        if( pos( '==', S ) > 0 ) then // Global
        begin
            Table := LNM_JOB ;
        end else
        begin
            Table := LNM_PROCESS ;
        end ;
        if( L > 0 ) then // Substring specified
        begin
            Context := LIB_Get_Symbol( Sym, Table ) ;
            while( length( Context ) < P ) do
            begin
                Context := Context + ' ' ;
            end ;
            while( length( Work ) < L ) do
            begin
                Work := Work + ' ' ;
            end ;
            setlength( Work, L ) ;
            Work := copy( Context, 1, P ) + Work + copy( Context, P + 1 + L, length( Context ) ) ;
        end ;
        Status := LIB_Set_Symbol( Sym, Work, Table ) ;
        Status := LIB_Get_Exception( 0 ) ;
        if( Status <> 0 ) then
        begin
            Work := LIB_Get_Exception_Text( 0, Status ) ;
            Set_Exception( Work ) ;
        end ;
        exit ;
    end ;
This routine is responsible for processing the assignment of a value to a symbol. First we check for a string assignment (starting with a colon). In this case, we get the value to assign. If that fails, we exit. Otherwise, we choose the appropriate table based on whether = or == was specified. The P and L parameters are used to indicate a substring assignment. They default to -1, which indicates that this is not a substring assignment. So, if L is 0 or more, we process the substring by getting the current symbol value and extending it with spaces if the position/length require it. Then we extend the assigned value based on the substring length, if it is too short. If too long, we trim the excess. Then we change the assignment value (in Work) to be the current value with the new value inserted in the proper position.

Either way, by this point, Work contains the value to assign to the symbol. So we set the symbol and check for an exception, setting up for reporting it if there was one. Then we exit. 

    // Expression assignment...
    if( L >= 0 ) then // Substring specified
    begin
        Set_Exception( UCL_ERT( UCL_IVCHAR ), '' ) ;
        exit ;
    end ;
    Work := Get_Expression( Err, Context, True ) ;
    if( Err <> 0 ) then
    begin
        Parser.Grab_Line ; // Ignore rest of the line
        Set_Exception( UCL_ERT( Err ), Context ) ;
        exit ;
    end ;
    if( S = '==' ) then // Global
    begin
        Table := LNM_JOB ;
    end else
    begin
        Table := LNM_PROCESS ;
    end ;
    Status := LIB_Set_Symbol( Sym, Work, Table ) ;
    Status := LIB_Get_Exception( 0 ) ;
    if( Status <> 0 ) then
    begin
        Work := LIB_Get_Exception_Text( 0, Status ) ;
        Set_Exception( Work ) ;
    end ;
end ; // Process_Assignment
If we fall through to this code, the assignment is a normal (non-string) assignment. We check for a substring specification, which isn't allowed in this case (and exit with an error). Otherwise we get the value to assign. Note that we pass True as the third parameter in the call to Get_Expression. This directs the function to normalize integer values. We choose the appropriate table to affect, as described above. Then we set the symbol's value and check for an exception and handle it if there was one. 

procedure Process_SubRange_Assignment( Sym : string ) ;

var Err : integer ;
    Context, S : string ;
    SLength, SPosition : string ;
    L, P : integer ; // Length and position
    In_Position : boolean ;

begin
    SLength := '' ;
    SPosition := '' ;
    In_Position := True ;
    S := Get_Parameter( Err, Context ) ;
    if( Err <> 0 ) then
    begin
        Output_Line( RH_SysError, UCL_ERT( Err ) ) ;
        if( Context <> '' ) then
        begin
            Output_Line( RH_SysError, '    \' + Context + '\' ) ;
        end ;
        exit ;
    end ;
The Process routine calls this function if an opening bracket ([) immediately follows the symbol name. We set up the initial state and grab the first value/token. We initialize the position and length values (SPosition and SLength variables) and set the flag that indicates we should be in the position field (just after the opening bracket). 

    while( S <> '' ) do
    begin
        if( S = ']' ) then // end of subrange
        begin
            if( In_Position ) then
            begin
                if( SPosition = '' ) then
                begin
                    Output_Line( RH_SysError, UCL_ERT( UCL_EXPSYN ) ) ;
                end else
                begin
                    Output_Line( RH_SysError, UCL_ERT( UCL_SYMDEL ) ) ;
                end ;
                exit ;
            end else
            if( SLength = '' ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_SYMDEL ) ) ;
                exit ;
            end ;
            SPosition := UCL_Strtoint( SPosition ) ;
            SLength := UCL_Strtoint( SLength ) ;
            if( strtoint( SPosition ) < 0 ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_INVRANGE ) ) ;
                Output_Line( RH_SysError, '    \' + SPosition + '\' ) ;
                exit ;
            end ;
            if( strtoint( SLength ) < 0 ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_INVRANGE ) ) ;
                Output_Line( RH_SysError, '    \' + SLength + '\' ) ;
                exit ;
            end ;
            if( strtoint( SLength ) > 0 ) then
            begin
                Process_Assignment( Sym, Get_Token, strtoint( SPosition ), strtoint( SLength ) ) ;
            end ;
            exit ;
        end else
We iterate through the tokens in a loop. When we encounter a close bracket (]), we've reached the end of the substring specification, so we have to validate the specification. If the In_Position flag is set, it means we never processed the length - and possibly not even the position. In that case, we display the appropriate error and exit. If we've moved to the length field, we check to see if the length was specified and exit with an error if not. Next we use the UCL_Strtoint function to normalize the numeric values. Then we verify that the values are not negative, exiting with an error if either is. If the length is 0, there is nothing to do. Otherwise we call the Process_Assignment routine, passing the position and length. 

        if( S = ',' ) then
        begin
            if( not In_Position ) then // Already processed length
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_SYMDEL ) ) ;
                Output_Line( RH_SysError, '    \' + S + Parser.Peek + '\' ) ;
                exit ;
            end ;
            In_Position := False ; // Moved to length value
            S := Get_Parameter( Err, Context ) ; // Get length value
            if( Err <> 0 ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( Err ) ) ;
                if( Context <> '' ) then
                begin
                    Output_Line( RH_SysError, '    \' + Context + '\' ) ;
                end ;
                exit ;
            end ;
        end ;
If the next token is a comma, we are moving from the position field to the length field. First, we check if the In_Position flag is cleared. If so, we already moved to the length field and this is an extra comma, so we exit with an error. Otherwise, we clear the flag and get the length value. 

        if( In_Position ) then
        begin
            SPosition := S ;
        end else
        begin
            // In length specification...
            if( ( S = '[' ) or ( S = ',' ) ) then // Already processed length
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_SYMDEL ) ) ;
                Output_Line( RH_SysError, '    \' + S + Parser.Peek + '\' ) ;
                exit ;
            end ;
            SLength := S ;
            S := Get_Token ;
            if( S <> ']' ) then
            begin
                Output_Line( RH_SysError, UCL_ERT( UCL_SYMDEL ) ) ;
                Output_Line( RH_SysError, '    \' + S + '\' ) ;
                exit ;
            end ;
            continue ;
        end ;
        S := Get_Token ;
    end ; // while( S <> '' )
end ; // Process_SubRange_Assignment
If we get here, we are processing one of the values. If the position flag is set, we simply set the SPosition value. Otherwise, we are processing the length field so we check for a couple invalid symbols and exit with an error if found. Otherwise, we set the SLength value and grab the next token. If the token is not the closing bracket (]), we exit with an error. Otherwise we continue the loop which will check for the bracket and do the final processing, as described above. If not processing the length field, we grab the next token and loop to process it.

In the next article, we will look at another UCL command.

 

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