8 File Storage

Opening a Data File

Data files must be opened before they can be accessed. Each file is opened and assigned a file number with the ASSIGN statement. Syntax for this statement is as follows:

There is also a statement XASSIGN, which can ASSIGN a file with no DATA extension. See below.

The ASSIGN statement sets up an internal table of file numbers to be used with the PRINT# and READ# statements. The file table has room for 20 entries, allowing up to 20 files to be open for each user, but maximal 10 files in a segment. One data file can be assigned up to seven file numbers. The assignment table remains in effect until a new program is loaded or run, or until a SCRATCH, SCRATCH P, STOP, or END is executed. See page 237 , later in this chapter, for more details. The file number is a numeric expression; its range is 1 through 10.

The optional return variable can be a simple numeric variable or array element and is set after execution to indicate various results. Its value is used to check for errors. If no return variable is specified, an error occurs if the file is not found or is the wrong type. Possible values returned by the return variable are listed and explained in the following table:

Comparison of Data Access Methods
Return Variable Meaning
0File available, assignment complete.
1File not found (same as error 56).
2File is protected.
4Access error (errors 91 through 93).
5Other error.

Here are some examples of how to use the ASSIGN statement:

100  ASSIGN #1 TO "DATA"
110  ASSIGN "Scores" TO #4,Return
120  ASSIGN "Scores" TO #5
130  ASSIGN #2 TO "Poker,Games"
140  ASSIGN #3 TO "Totals:F2,6,1"
Line 110 illustrates a return variable. Lines 110 and 120 show that a file can be assigned more than once. Lines 130 and 140 show that the file spec can include either a volume label (Games) or a unit spec (F2,6,1).

The optional class list parameter provides flexibility in determining the type of file access. The following class words are available--EXCLUSIVE, UPDATE, READONLY, or APPEND.

Only one of the three words can be used at a time. Thus, if EXCLUSIVE is specified, UPDATE or READONLY cannot be used. To explain further, the following statement assigns the file named PAYROL to file number 1 and specifies read-only access:

EXCLUSIVE means that only one access may exist to the file anywhere in the system, but the same process can assign the file more than once. The file may not be assigned elsewhere; if anyone attempts this, an error occurs. Once a file has been assigned in exclusive mode, any attempt by the current program, or any other user's program, to assign the file results in an error. If no class list is specified, EXCLUSIVE is assumed. READ# and PRINT# statements may be done on the file without regard to locking. LOCK# and UNLOCK# are ignored if executed on a file assigned to exclusive mode. SORT workfiles must be assigned in exclusive mode.

If UPDATE is specified, shared access is granted to the data file. The ASSIGN fails, however, if there are any other references to the data file in either read-only or exclusive mode. Once a file has been assigned in update mode, READ# operations may be done. In order to PRINT to the file, however, the LOCK# statement must be used to gain write access. The LOCK# statement causes an error if the file is already locked by the current program through another reference.

If READONLY is specified, shared read access is granted to the file. The ASSIGN fails if there are any other references to the file in either update or exclusive mode. Once a file has been assigned in read-only mode, READ# operations may be done. There is no way to write to a data file assigned to read-only mode. The LOCK# and UNLOCK# statements are ignored if executed on a file assigned to read-only mode. The GET, LINK, and MERGE statements require read-only access to the file being accessed.

The APPEND file mode causes all output to a HP-UX sequential file automatically appended to the end of the file.

If a file is opened in APPEND mode, it will behave different:

For example:

PRINT #1;DATE$;TIME$;"Message"
The example code above will cause output appended to Logfile. If Logfile does not exist, it will be created.

Note that in order to guarantee that the data being read from a data file is correct, the file must be LOCKed. If not, the data may be old (since data files do not use the sophisticated buffering scheme employed by Eloquence DBMS). It is also possible that the data on the disk has been only partially updated by the user who has the data file locked. In this case, an actual error may occur during a read. So, unless some special agreement exists between programs altering a file in update mode, it is best to also lock the file before reading.

The XASSIGN statement assigns a file of the type specified. This could be any hp260 file type (DATA, PROG or FORM). If the type is OTHR, no extension will be added to the filename.

XASSIGN # file name TO file name; file type [,assign_options]


   XASSIGN #1 TO "/etc/passwd";OTHR;READ ONLY 
will assign #1 to


Data Pointers

A record pointer is automatically maintained for each opened data file. This pointer is used to specify at which record data storage or retrieval begins in the data file. A word pointer is also maintained for each current record. It points to the first word of the next data item to be accessed in the record.

After executing an ASSIGN statement, the record pointer is positioned at the beginning of the first logical record in a data file. The word pointer is then incremented through the record as data items are stored (PRINT#) or retrieved (READ#). A new ASSIGN statement obsoletes the previous one and resets all pointers for the specified file.

The current position of each pointer can be found by using the REC (record) and WRD (word) functions, as described later in this chapter.

Converting a Text File

The 'convrt' program converts text files from HP-260 format into HP-UX ASCII format. The resulting file is assigned the same name as the HP-260 file plus the extension '.txt' in the current directory. If the file already has an extension, it will be overwritten to '.txt'.

The syntax is as follows:

convrt [options] file [file]


Detailed listing of procedures
Write to stdout
Show file or files to be converted.


To convert text files dbmap1.DATA und dbmap2.DATA into HP-UX format:

convrt -v dbmap*.DATA

NOTE: The 'convrt' program converts text files, or parts of a file containing text until non-text data is detected.

Eloquence Language Manual - 19 DEC 2002