HP 3000 Manuals HP 3000 Manuals
FILE Command (Serial)
The file command allows you to perform various operations on application
data files. You can use the file command to perform operations on HP
ALLBASE/SQL tables and select lists, HP TurboIMAGE/iX data sets, KSAM
data files, and serial data files.
This description covers the use of the FILE command to perform operations
on serial files.
Formats
{*BUFFER }
{*CLOSE }
{*FIRST }
FILE {*LAST } file_ref [;command]
{*MODIFY }
{*NEXT }
{*PREVIOUS}
{*REMOVE }
{*INSERT}
FILE {*READ } file_ref[*REC=record_number][;command]
{*WRITE }
Window
![[]](../../pic3k/M012319/FFN153c50.gif)
Parameters
file_ref
Specifies the HP ALLBASE/4GL name of the serial file on which the
operation is to be performed. You can express this as:
* file_id
- or
* file_id.record_name
If you don't specify .record_name for the file, HP ALLBASE/4GL uses the
default record for the file.
record_number
HP ALLBASE/4GL allows you to access a fixed length record serial file
record by specifying the number of the record. Record number 1 is the
first physical record in the file. You can also use a record number with
the FILE *INSERT operation for a fixed length record serial file. In
this case, the record number specifies the number of the record that is
overwritten by the current contents of the file record buffer.
You can specify record_number with any of the following items containing
a non-negative integer number.
* A whole number.
* A numeric constant.
* A variable or calculated item.
* A screen field reference.
* A scratch-pad field reference.
* A file record field reference.
* A work area field reference.
* A communication area field.
command
A command to be executed if the requested file operation fails. You can
use any of the following HP ALLBASE/4GL logic commands:
* ENTER
* EXIT
* EXTERNAL
* MESSAGE
* PROCEED
* SERIES
* TOP
* VISIT
* ZIP
Description
The FILE command allows you to perform various operations on serial
files.
HP ALLBASE/4GL supports serial files with fixed length records, or
variable length records.
Fixed length record serial files have records that contain a fixed number
of characters as defined by an HP ALLBASE/4GL record layout.
When HP ALLBASE/4GL reads a record from a variable length serial file, it
reads characters until it encounters the end of the record. Characters
read from the file are read into the file buffer as defined by the record
layout specified on the FILE command.
If HP ALLBASE/4GL reads fewer characters than the length of the file
buffer, the unused characters in the buffer are filled with spaces.
If you attempt to read a record longer than the record buffer, HP
ALLBASE/4GL reads the number of characters that the buffer can
accommodate, and sets the switch *MOREREC on. The next FILE *READ
command or FILE *NEXT command either reads the remaining characters in
the record, or reads the number of characters that the buffer can
accommodate and then sets *MOREREC on again if the record still contains
unread characters.
HP ALLBASE/4GL substitutes space characters for all non-printable
characters and control characters read from serial files.
When HP ALLBASE/4GL writes to a fixed length serial file, it writes the
data contained in the current file record buffer. The number of
characters written to the file is determined by the length of the default
record for the file. If the current record layout is longer than the
default record layout for the file, the additional characters are
truncated.
When HP ALLBASE/4GL writes to a variable length record serial file, the
length of the record written to the file is determined by the length of
current record layout. HP ALLBASE/4GL discards any trailing blanks.
You must specify any serial files that are to be updated by the FILE
command in the current process by using a MODE command with the *WRITE
argument. Any files not specified in the MODE command cannot be updated
or modified from HP ALLBASE/4GL logic and are available for reference
purposes only. (Refer to the MODE command.)
When accessing a serial file, HP ALLBASE/4GL places the external name of
the file in the communication area field *FILENAME.
If the file has fixed length records, HP ALLBASE/4GL places the number of
the record read or written in the communication area field *RECNO.
Serial File Creation
If a serial file does not already exist, HP ALLBASE/4GL automatically
creates it when the application first accesses the file. The process
containing the FILE command that creates the file must contain a MODE
*WRITE file_name command to give the process write access permission to
the file.
The dictionary data file creation screen does not allow you to create
serial files.
Temporary Serial Files
HP ALLBASE/4GL allows you to specify the external name of a serial file
as *TEMP on the dictionary file definition screen.
HP ALLBASE/4GL creates a temporary file when the application first
accesses the the file. The file is deleted when you close it, or at the
end of the process. The process must contain a MODE *WRITE file_name
command.
HP ALLBASE/4GL creates temporary serial files in the temporary domain of
the user's current group and account.
Dynamic File Naming
HP ALLBASE/4GL allows you to define a serial file with the external name
specified as *FILENAME on the dictionary file definition screen.
By moving the external file name into the communication area field
*FILENAME before HP ALLBASE/4GL executes the FILE command that opens the
file, you can specify which file the command operates on.
Normally, HP ALLBASE/4GL appends the current value of the MPE/iX variable
HP4DATAPATH to the value in *FILENAME to determine the external name of
the file. However, if *FILENAME contains a fully qualified file name,
(that is, a file name in the form FILE.GROUP.ACCOUNT), HP ALLBASE/4GL
performs the operation on the file specified by this name.
Error Handling
If the FILE command contains an optional error command, HP ALLBASE/4GL
executes the command if an error occurs as a result of the file access.
For example, when performing a *NEXT operation HP ALLBASE/4GL executes
the optional command if the end of the file is encountered.
When an error occurs, the data manager writes an error code into the
communication area field *IOSTATUS. Appendix C lists the data manager
error codes. The value in *IOSTATUS is zero if the file command is
successful.
If you include the optional error command, the data manager error
messages will not be displayed on the terminal screen.
File Errors
The following table summarizes the most common file error values returned
to the communication area field *IOSTATUS. Refer to appendix C for a
complete list of error returns.
*IOSTATUS
Value Condition
19002 File does not exist
19013 Access permission denied
19110 Beginning or end of file encountered by a FILE *NEXT or FILE
*PREVIOUS command.
File Record Buffers
HP ALLBASE/4GL maintains a separate buffer for each record layout for a
serial file.
HP ALLBASE/4GL clears the file record buffers automatically when a file
is first accessed, or at the start of any process.
Serial File Locking
HP ALLBASE/4GL does not provide any locking mechanism for serial files.
Transaction Logging
HP ALLBASE/4GL does not provide any transaction logging or transaction
roll-back mechanism for serial files.
File Operations
Operations that may be performed on serial files are:
*BUFFER. Sets all fields in the specified file record buffer to spaces.
The buffer cleared is defined by file_ref.
*CLOSE. Closes the nominated file. If the file is a temporary file, this
operation also deletes the file.
*FIRST. Reads the first record in the file.
*INSERT. For both fixed length record files and variable length record
files, this operation adds a new record to the end of the file. For
fixed length record files only, this operation overwrites the record at
the specified position if you use the *REC=record_number argument.
Record number 1 is the first physical record in the file.
*LAST. Fixed length record serial files only. This argument reads the
last record in the file.
*MODIFY. Fixed length record serial files only. This form of the command
changes the contents of the current record. You must read a record
before you can use the *MODIFY argument to change it.
*NEXT. Reads the next record in the file. If a FILE *NEXT command
encounters the end of file, the value returned to *IOSTATUS is 19110.
For variable length record files, HP ALLBASE/4GL sets the switch *MOREREC
on if the current record contains more characters than the buffer can
hold. The next FILE *NEXT or FILE *READ command retrieves the remaining
characters in the record. If the current record is the same length as
the file buffer or shorter than the buffer, the switch *MOREREC remains
off.
*PREVIOUS. Fixed length record serial files only. This command reads the
previous record in the file.
*READ. Reads the next record in the file. For fixed length record serial
files only, you can use the *REC=record_number argument to read a
specific record. Without the *REC= argument, this operation is identical
to the *NEXT operation. Record number 1 is the first physical record in
the file.
For variable length record files, HP ALLBASE/4GL sets the switch *MOREREC
on if the current record contains more characters than the buffer can
hold. The next FILE *NEXT or FILE *READ command retrieves the remaining
characters in the record. If the current record is the same length as
the file buffer or shorter than the buffer, the switch *MOREREC remains
off.
*REMOVE. Physically deletes the file. The file is deleted regardless of
the mode specified for the file in the current process.
The user must have the correct MPE/iX authorities to be able to delete
the file.
*WRITE. Adds a record to the end of the file. For fixed length record
serial files you can use the *REC= argument to specify the number of the
record to be written. This form of the command overwrites the record at
the position identified by *REC.
Example 1
1 MODE *LOCK outfile
2 FILE *FIRST infile; ENTER 7
3 MOVE R-infile R-outfile
4 FILE *INSERT outfile; ENTER 8
5 FILE *NEXT infile; ENTER 7
6 ENTER 3
7 IF *IOSTATUS = N-end_of_file
THEN MESSAGE read_complete; EXIT
ELSE MESSAGE infile_error; EXIT
8 MESSAGE outfile_err
9 EXIT
This logic block shows a technique for importing data from a serial file
infile and writing it out to an indexed file or an HP ALLBASE/SQL table
outfile for use in an HP ALLBASE/4GL application.
Both files use the same record layout format. Records read from the
input serial file are moved from the record buffer for the input file to
the buffer for the output file and written to the output file. The
process continues until an error condition occurs by reaching the end of
the input file.