|
![]() | ![]() ![]() ![]() ![]() ![]() ![]() ![]() | Reading and Writing Files |
File references in VisualPQL programs are to the attribute name which allows applications to operate on different physical files without altering program code. For example, the attribute for the first file in the first database is always SIR00011
. This is mapped at execution time to a specific operating system file depending on the start directory such as C:\mydir\myproject\projdb.sr1
.
Attribute names may be specified by a program, may be the filename if it meets the specification of a SIR/XS name or may be system generated such as SYSUSR1
. When using SIR/XS interactively, you can inspect and modify attributes through the Settings/File Attributes menu.
Specific, named attributes are created by various VisualPQL and general SIR/XS commands including OPEN
and SET ATTRIBUTE
. When specifying long filenames on the OPEN
command, this may be done at compile time with the name in quotes in a DSN
(Data Set Name) clause or at execution time using the DSNVAR
(Data Set Name Variable) clause which specifies a string variable that will contain the filename.
When a VisualPQL command makes a reference to a filename that is not in quotes, if it is a valid SIR/XS name, it is checked against the current set of attributes. If a match is found, the full filename that the attribute refers to is used. If it doesn't match, then a new attribute is created with that name pointing to a file in the current default directory. A temporary attribute with an internal name is automatically created for any other name and this is deleted at the end of the program execution. Specify a file name in quotes if it contains characters such as slash, comma or blank that have meaning in VisualPQL. For example:
READ ( 'D:\SIRDB\EMPDB\DATA\REC1.DAT' ) DATALINE (A20)
- reads the specific file using a temporary attribute which is deleted at the end of execution.
READ ( REC1.DAT ) DATALINE (A20)
- reads the specific file using a temporary attribute which is deleted at the end of execution.
OPEN MYFILE DSN='D:\SIRDB\EMPDB\DATA\REC1.DAT'
- reads the specific file using an attribute called
READ ( MYFILE ) DATALINE (A20)MYFILE
which is kept past the end of execution.
Programs can read from and write to named files. These may be text or binary files and output files can be newly created or opened in append mode, which adds to the end of any existing file of the same name.
A file can be read or written without being specifically opened. If a file is referenced on a READ
command and the longest record in that file is 80 characters or less, it is automatically opened. If a file is referenced on a WRITE
command, it is automatically opened with the same record length as the current default output. By default, this is 120 characters. To open a file with any other characteristics, use the OPEN
command.
By default, output files are new files and overwrite any existing file without issuing a warning. Use the APPEND
option on the OPEN
command to append to an existing file of the same name. A new file is created if it does not exist.
If a WRITE
does not specify a file, output is to the default output file. In an interactive session, the default output file is the scrolled output window, but can be assigned to a file. Batch runs always have output assigned to a file.
BINARY
keyword on the OPEN
command and binary format specifiers on the READ
and WRITE
commands. Integers and real numbers in a binary file are in internal computer formats and a binary file does not have end of record markers. Reading and writing binary files means that exactly the number of bytes specified in the read or write variable list are transferred between the file and the program. It is the programmer's responsibility to ensure that file and variable specifications match.There are three formats that specify that binary data is being transferred.
HEXw
format is for generic strings of binary data and these are not altered in any way by the read/write process. The w specifies the length of field and can be up to 4094. Declare the variable being used as a normal VisualPQL string. If strings are written as text using the A format as opposed to Hex format, if the string contains a hex character '00', it is taken as the end of any text output line and the line is truncated to that point.IBw
and RBw
formats allow the transfer of numeric data. IB
is for Integers in Binary format and RB
is for Reals in Binary format. The w specifies the length of field and is 1,2 or 4 for integers, 4 or 8 for reals.program integer*1 ibyte1 string*256 a256 string*250 oldfl newfl real*8 cnt fsize cnt=0 c ** Change these names to required filenames compute oldfl = 'splash.bmp' compute newfl = 'copy.bmp' compute fsize=filestat(oldfl,10) open inf dsnvar=oldfl lrecl=256 binary open outf dsnvar=newfl lrecl=256 binary write loop cnt=cnt+256 ifthen(fsize-cnt ge 256) . read (inf,error=end) a256(HEX256) . write (outf) a256(HEX256) else c Less than 256 bytes left so go 1 byte at a time . loop . read(inf, err=end)ibyte1(ib1) . write(outf )ibyte1(ib1) . end loop endif end loop end: end program
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
OPEN fileid [ BINARY ] [ DELETE ] [ DSN = 'file_name' | DSNVAR = str_varname | | LDIVAR = str_varname ] [ DYNAMIC ] [ ERROR = statement_label ] [ IOSTAT = num_varname ] [ LRECL = max_rec_length ] [ MEMBER [ REPLACE ] ] [ READ | WRITE [APPEND]]
Opens the specified file or member for READ
or WRITE
access, READ
is the default. Files are accessed by the READ
and WRITE
commands and these commands automatically open a file which has not been specifically opened. The CLOSE
command can reference any open file whether specifically opened or opened automatically. A file is closed automatically when the program execution finishes. A file can be re-opened to change modes without closing. A program cannot read from a file opened with write access nor write to a file opened with read access
Note that the options on OPEN
are not enclosed in parentheses whereas the clauses on READ
and WRITE
are specified within parentheses.
fileid
|
The fileid is the name referenced by any subsequent READ, WRITE or CLOSE commands. It is recommended that this is an attribute name and a DSN clause specified, however a filename, possibly in quotes, is allowed.If a member is being referenced and a DSN clause is not specified, the fileid is the member name, the current default family name is used and the current default procedure file is used. Since the user can easily change procedure files and families, it is normal practice for the fileid to be an attribute and to fully specify the procedure file, family and member in a DSN clause. |
APPEND
| Specifies that the opened file is added to the end of any existing file with the same name. If the file does not exist, it is created. |
BINARY
|
Specifies that the opened file is treated as a binary file. Data is read or written exactly as given and no translation to text takes place. There are no end of line or end of record markers.
To illustrate the differences between writing text and binary:-
|
DELETE
|
Specifies that the opened file (or member) is deleted after it is closed. Files are closed when a CLOSE command is executed or at termination of the program. The CLOSE command also has a delete option. |
DSN | DSNVAR | LDIVAR
|
DSN specifies a fully qualified external filename enclosed in quotes.DSNVAR specifies the name of a string variable that contains the fully qualified filename. A value of asterisk (*) specifies that the default input or output files are used that may be useful during program development and debugging.LDIVAR specifies the name of a string variable that contains the attribute name of the file. A value of asterisk (*) specifies that the default input or output files are used that may be useful during program development and debugging.
|
DYNAMIC
|
When a subroutine is compiled, the OPEN command can create references to files which would be incorrect or in conflict with the calling routine when the subroutine is subsequently loaded at execution time. DYNAMIC specifies that the file attribute entry is not stored with the saved subroutine object code.Has no effect if the OPEN is in a PROGRAM or RETRIEVAL . |
ERROR
|
Specifies a statement label where control is transferred if an error occurs in opening the file. If the ERROR clause is not specified and an error in opening the file occurs, an error message is displayed and program execution terminates. |
IOSTAT
|
Specifies a numeric variable to hold a return code. If IOSTAT is specified and an error occurs, a value is assigned to the specified variable and control transfers to the ERROR clause statement label. If there is no ERROR clause, execution continues with the next statement. If IOSTAT is not specified and an error occurs a message is printed and the program is terminated. The codes for normal files are: |
LRECL
|
Specifies the longest record length (in bytes) on the file being opened. If LRECL is not specified, 80 bytes for READ and the current default output width (that itself defaults to 120) for WRITE are used. If a record longer than the specified length is encountered, the record is truncated and a warning message is issued.
If the file is a binary file, even though there are no records as such and the lengths read or written depend on the i/o specifications, the |
MEMBER
|
Specifies that the fileid is a procedure file member. Once opened, a member can be read from or written to. Only one member of the procedure file may be open at any given time. If a member is not explicitly closed with the CLOSE command, it is closed at the termination of the program. |
REPLACE
|
REPLACE gives permission to overwrite an existing member. If the specified member does not exist, this keyword has no effect. If an attempt is made to write to an existing member and this keyword is not specified, the member is not overwritten and an advisory message is issued. A family cannot be created with an OPEN command. |
READ | WRITE
|
READ, the default, opens the file or member for read access. WRITE opens the specified file or member for write access. |
For example:
OPEN MYFILE DSN = "TESTATTR.TXT" WRITE
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
CLOSE fileid [DELETE]
Closes the specified file. CLOSE
may be used to close a file early in a program in order to reopen it later during the same program. Closing and then opening a file allows the program to re-read the file from the beginning.
DELETE
| The file or member is deleted when it is closed. |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
DELETE PROCEDURE FILE MEMBER name
Removes the named procedure file member at execution time. The name may be a string constant, a string variable or string expression. The type (a type letter following the colon) must be specified. Any member type may be deleted. The delete option on the OPEN/CLOSE
commands can only be used with text members.
The format of the name is the normal member name format i.e.:
[procedure_file_attribute.][family[/pword].]member[/pword]:type
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
READ ( fileid [ERROR=label] [IOSTAT=VARNAME] [MEMBER] [DYNAMIC] ) i/o_list
READ
reads data from the specified file according to the i/o list which specifies how values read from the input are assigned to program variables.
Note that the options on READ
up to the i/o list are specified within parentheses.
If the file is a normal text file, records are read from first to last sequentially and a new record is read each time a READ
of the file is executed. Each read reads a single record and fields from the file are translated into appropriate internal formats.
If the file is a binary file, input fields must match the type of the fields on the file in order to process data correctly and data is read according to the number of bytes specified on the i/o list.
If an explicit OPEN
command has not been executed, the first time the READ
is executed the file is opened. If the file cannot be opened successfully, an error message is displayed and the program stops executing. If an explicit CLOSE
command is not executed, program termination closes the file.
A READ
command is not a block control statement and simply executes without looping. In order to read through a complete file, it is necessary to enclose the READ
in a looping block, typically a WHILE (IOSTAT = 0)
.
An IOSTAT =
varname may be specified as a return code. An ERROR =
label specifies where the code is to deal with error conditions and this receives control when any non-zero return code is encountered on the READ
. A read at end of file returns error code -4; programs normally treat any non-zero return code as end of file.
PROGRAM STRING * 80 LINE INTEGER*1 STAT STAT = 0 WHILE (STAT = 0) . READ(INPUT.TXT,IOSTAT = STAT)LINE(A80) . WRITE LINE(A80) | display what was read END WHILE END PROGRAM
fileid
| Specifies the name of the input file or member. This may be a filename or an attribute name. |
ERROR
| Specifies a statement label in the program. Control is passed to that point if an error or end-of-file condition occurs. |
IOSTAT |
Specifies an integer variable for a return code. Return codes are: 0 Success -1 File not Open -4 End of File |
MEMBER |
Specifies that the file being read is a member from the procedure file. This is unnecessary if already specified on an explicit OPEN .
|
DYNAMIC |
Specifies that file attribute entry is not stored with the subroutine object code when compiled. |
i/o list |
Specifies the individual formats for the variables to be read. The list consists of local variable names followed by the appropriate format specification in parentheses. If a variable name is not followed by a format specification, the first following format specification applies to all previous variables without a format. The formats can be fixed-field, free-field or pictures, and can contain positional specifiers i.e. skipping input columns or positioning to specific input positions. For example: READ (DATAFILE.DAT) RECTYPE(I1) NAME(A20) 3X SEX ETH_CODE RANK(I1) Detailed descriptions of the input formats follow. |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Iw Integer, w digits wide
Fw.d
Real single precision, w digits wide, d decimal places
Ew.d
Real, scientific notation
Dw.d
Real double precision, w digits wide, d decimal places
Aw
String, w characters wide
Bw
String, characters reversed (backwards)
DATE 'format'
Date in specified date format.
TIME 'format'
Time in specified time format.
nX
Skip the next n columns.
nT
Tab (move) to column n before reading the next variable. Column n can be before or after the current position.
HEXw
Binary string, w digits(up to 4094)
IBw
Binary integer, w digits(1,2 or 4)
RBw
Binary real, w digits (4 or 8)
HEXCHARn
Read hex codes as characters.
* Any free-field variable
I*
Integer
A*
String
The following numeric free field formats are all synonymous. These will all process delimited fields in either normal or scientific notation:
F*
Real
E*
Real, scientific notation
D*
Real, double precision
A
any letter
U
any uppercase letter
L
any lowercase letter
9
blank or any character valid in a numeric string. These characters are any digit, plus and minus, the letter "E" and a decimal point.
Z
any character valid in in a numeric string. Same as '9' except blank not allowed.
D
any digit
S
any character valid in in a numeric string. Same as Z
For example, if the expected input is a string in a format such as XXX-XX-XXXX
, the picture might be 'CCC-CC-CCCC'
. However, if the data is expected to be numbers between the hyphens, the picture might be 'DDD-DD-DDDD'
.
If the expected input is a number taking say 9 characters including a fixed decimal position with two decimal places, the picture might be '999999.99'
. Note that, if special characters such as a $ sign or an asterisk may or may not be in the data ('floating'), or may or may not contain commas depending on the size of the number, it is advisable to read the data as a fixed length string and apply specific formatting within the program.
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
READ [ 'prompt_text'] i/o_list [ 'prompt_text'] i/o_list ...
It is recommended that interactive read is not used. Use DISPLAY TEXTBOX
instead.
Interactive READ
reads input from the user, popping up a box with the specified prompt (a question mark ? is displayed if no prompt text), space for data entry and response buttons that allows entry of data. The program waits for the user to enter data. Regardless of the number of fields on the input specification, a single box is popped. (If multiple boxes are wanted, specify multiple prompts and i/o lists.) Input fields are delimited by spaces. The user must enclose a string input field in quotes if it contains spaces.
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
REREAD ( fileid [ ERROR=label ] [ IOSTAT=varname] [DYNAMIC] )
i/o_list
Rereads the last record read from the specified sequential file. The syntax for the command is the same as the READ
command.
The REREAD
may specify a different input specification than used on the previous READ
. For example:
PROGRAM STRING*80 TEXTLINE STRING*20 STUDENT INTEGER*1 RECTYPE NAME SEX ETH_CODE RANK READ (DATAFILE.DAT) RECTYPE(I1) NAME(A20) 3X SEX(I1) ETH_CODE(I1) RANK(I1) IFTHEN (RECTYPE = 2) . REREAD (DATAFILE.DAT) RECTYPE (I1)TEXTLINE(A80) ENDIF ...pql commands END PROGRAM
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
WRITE ( fileid [ERROR=label] [IOSTAT=varname] [MEMBER [REPLACE]] [NOEOL] [DYNAMIC] ) i/o_list
WRITE
writes data to the specified file from the specified program variables according to the i/o list.
Note that the options on WRITE
up to the i/o list are specified within parentheses.
WRITE
with a specified fileid writes to a file or to a procedure file member when MEMBER
is specified either on the command or on a previous explicit OPEN
for this fileid (attribute).
WRITE
creates a new file or new member unless the APPEND
option is specified on a previous explicit OPEN
for this fileid (attribute), which then writes records to the end of the specified file or member.
If there is no fileid specified, the command writes output to the scrolled output which may be the screen or assigned output file. Pages are automatically maintained when standard output is assigned to a file but there is no paging on interactive screen output. (Note that no further options can be specified if the fileid is not specified. See below for special fileids for standard output.)
Each time the WRITE
is executed, if the output is a text file (not binary) or member, a new record is created unless the NOEOL
option is specified.
If the output is a binary file, fields are written to the end of the specified file.
Output is formatted according to the i/o list and values are assigned from the program variables to the output. If the output is a binary file, the exact values from the program variables are written in the internal format of those variables if they are strings or if the binary formats are used.
fileid |
Specifies the name of the output file or member. This may be an attribute or filename.
If any options are specified, the fileid must be specified. If default output is wanted when other options are specified, use
The filename
|
ERROR = label |
Specifies a statement
label in the program. Control is passed to this label if an error condition occurs on the command. If the ERROR or IOSTAT clause is not specified and an error occurs, an error message is written and the program is terminated. |
IOSTAT
|
Specifies the name of a numeric variable that returns any error code. The value zero indicates no error, a negative number indicates the type of error that occurred. |
MEMBER [REPLACE] |
Specifies that the file being written is a member from the procedure file. This is unnecessary if already specified on the explicit OPEN .
|
NOEOL |
Specifies that the output is written without an end of line. The next WRITE simply continues putting data to the file and no new record is created. This can be used to build a complete file in a particular format without any end of line characters or can be used interspersed with WRITE commands that do create end of line. |
DYNAMIC |
Specifies that file attribute entry is not stored with the subroutine object code. Normally a subroutine stores the current value of the file attribute and that is restored at
runtime to ensure that the program works consistently. If the file attribute is intended to be set prior to each call of the subroutine then the DYNAMIC keyword will prevent the
old attribute from being reused.
|
i/o list |
Specifies the individual formats for the variables to be written. The list consists of local variable names followed by the appropriate format specification in parentheses. If a variable name is not followed by a format specification, the first following format specification applies to all previous variables without a format. If a slash '/' is specified, the record is written at that point and the next line started. String constants (characters enclosed in quotes) can be specified and are written out as specified. Do not specify an output format for string constants. The formats can be fixed-field, free-field or pictures, and can contain positional specifiers that skip output characters or position to specific output positions. If no format is specified, the format is taken to be free field. Format specifications for date, time and categorical variables may be numeric or string.
For example: WRITE (DATAFILE.DAT) RECTYPE(I1) NAME(A20) 3X SEX ETH_CODE RANK(I1) OPEN MYPROC DSN = 'SYSPROC.TEST.TEST1' MEMBER APPEND | Procedure_file.Family_name.member_name WRITE (MYPROC) 'CCCCCC' To specify an expression in an output specification, enclose it in square brackets. The value of the expression is calculated and output according to the output format at execution time. For example: WRITE (cgi) ['<' + 'script language="javascript" type="text/javascript" src="'+FNAME1+'">'] Detailed descriptions of the output formats follow. |
![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Iw
Integer, w digits wide
Fw.d
Real single precision, w digits wide, d decimal places
Ew.d
Real, scientific notation
Dw.d
Real double precision, w digits wide, d decimal places
Aw
String, w characters wide up to 4094
Bw
String, characters reversed (backwards)
DATE 'format'
See date formats for a complete description. For example:
WRITE XBEG (DATE 'MMM DD, YYYY')
TIME 'format'
See time formats for a complete description. For example:
WRITE ALARM (TIME 'HH:MM:SS')
CHARHEXn
Write characters as hexadecimal codes. Specify the number of input characters. Each code takes two characters to output so the output produced is twice the length specified. The hexadecimal value for '1' is 31, so the output is the characters '31' (hexadecimal 3331). If the character values are shorter than specified, trailing spaces (hex value 20) are output as the characters '20'.
BINARY
option on the OPEN
is essentially the same as specifying NOEOL
on each WRITE
command. It is recommended that the binary specification is used where this is applicable. If both binary and NOEOL
are specified, data may not be written at end of file correctly.Any field format can be used on any type of file i.e. binary formats can be used on 'text' files and text fields on 'binary' files if that is the required format. Binary numeric formats can be specified for numeric fields i.e. a RB8 format could be specified for an integer variable. However, the differences in the output produced should be clearly understood.
The following defaults are used for free field formats:
To output a single array element, specify the dimension(s) in parentheses in the normal way for referencing array elements before any format specification. Multiple elements can be written, all with the same format, with the
Multi-dimensional arrays are printed so that entry (1,1) is first, (2,1) is second through to (n,1) that is followed by (1,2) etc. For example:
Each digit can be represented by "9", "Z", "*" or "$":
A period (.) represents the decimal point and separates the specification into characters before and after the decimal point. There can only be one period in the picture. After the decimal point, the special characters "9", 'Z', "$" and "*" are all equivalent and specify a digit.
Specify comma (,) to insert this character. If leading zeros are suppressed, any leading commas are suppressed.
By default, negative numbers are output with a minus sign ahead of the first significant character. If an explicit minus sign is included as the last character in the picture, and the number is negative, the minus is written at that point.
Any other characters are output at the position specified in the picture.
If there are insufficient digits to display the integer portion of the field (including any minus sign when negative and $ when specified), the field is written as all 'X's. The decimal component is rounded to match the number of decimal digits specified. If there are no decimal digits in the picture, the field is rounded to the integer value.
For example:IB1 IB2 IB4
Integer*1, 2 or 4 binary value. If a single text digit is written, the hexadecimal value is that of the character e.g. '1' is written as hexadecimal 31. A value of 1 with an IB1 format is hexadecimal 01. If the same value is written as IB2 it is 0100 and as IB4 it is 01000000.RB4 RB8
Real*4 or Real*8 binary value. If a real value is written as text, it is either written according to a specified format or in a format that best represents the value and the hexadecimal value is that of the character e.g. again '1' is written as hexadecimal 31. A value 1 written as RB4 takes four positions with values such as 0000803F and as RB8 takes eight positions with values such as 000000000000F03F.HEXn
Writes up to 4094 characters in a similar way to the An string format with two small differences. First the field is extended with trailing blanks to the specified length when An is specified and with binary zeroes (Hex 00) when HEXn
is specified. Second, any embedded binary zero is replaced with space when written with An format.Free-field formats
*
Any free-field variableI*
IntegerF*
RealE*
Real, scientific notationD*
Real, double precisionA*
StringHEX*
StringCHARHEX*
String as hexadecimal codes.Positional specifiers
nX
Skip the next n columns before writing the next variable.nT
Move (Tab) to column n before writing the next variable. n must be 1 or greater.Array Element Printing
nE
Output n more elements of previous array.nE
specification which outputs the next n elements of the array. Specify the nE
(not in parentheses) after any format. n must be 1 or greater.
INTEGER*1 ARRAY ARR1 (3,4)
SET ARR1 * (10,11,12,13,20,21,22,23,30,31,32,33) | Twelve elements - same sequence on output
WRITE ARR1 (1,1) (I4) 11E
Picture clauses
A picture can be specified for numeric fields as a format. A picture is a string of characters, enclosed in quotes where certain characters have special meanings.
"9" specifies that leading zeros are replaced by blank. If the field has a value of zero, a picture of all "9"s results in blanks; if a single zero is wanted, specify a single "Z" as the last character of the picture.
"Z" specifies that leading zeros are written.
"*" specifies that leading zeros are replaced by "*".
"$" If a single dollar sign is specified, it is output in that position. Multiple "$" characters represents a floating dollar sign where leading zeros are suppressed and results in a single dollar sign in front of the first significant digit. If the field has a value of zero, a picture of all "$"s results in blanks; if a single zero is wanted, specify a single "Z" as the last character of the picture.
PROGRAM
c The following formats produce following output
WRITE [123.4] ('$ZZ,ZZZ.99-') | $00,123.40
WRITE [123456789] ('ZZZ-ZZZ-ZZZ') | 123-456-789
WRITE [-123.4] ('99,999.99') | -123.40
WRITE [-123.4] ('$99,99Z.99') | $ -123.40
WRITE [-123.4] ('$$,$$Z.99') | -$123.40
WRITE [-123.4] ('ZZ,ZZZ.99') | -0,123.40
WRITE [-123.4] ('$ZZ,ZZZ.99') | $-0,123.40
WRITE [-123.4] ('99,999.99-') | 123.40-
WRITE [-123.4] ('$99,99Z.99-') | $ 123.40-
WRITE [-123.4] ('$$,$$Z.99-') | $123.40-
WRITE [-123.4] ('ZZ,ZZZ.99-') | 00,123.40-
WRITE [-123.4] ('$ZZ,ZZZ.99-') | $00,123.40-
WRITE [1234.56]('$*******.**') | $***1234.56
WRITE [1234.56]('Z Z Z Z . Z Z') | 1 2 3 4 . 5 6
WRITE [1234.56]('ZZZZ') | 1235
END PROGRAM
The same picture specifications apply to the PFORMAT
function.