Home Starting Environment DBMS VisualPQL Procedures SQL Forms Host/API Index

VisualPQL

Reading and Writing Files

An interactive program can READ without naming a file. This displays a text box for the user to enter data. 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.

The OPEN command is optional. 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. Use the APPEND option on the OPEN command to append to existing files of the same name.

Filenames

READ ( 'D:\SIRDB\EMPDB\DATA\REC1.DAT' ) DATALINE (A20)

SIR/XS uses a short, internal, name or Attribute that is mapped to the long, fully qualified filename. If a filename is a valid SIR name not in quotes, it is checked against the current set of attributes. If a match is found, the full filename that the attribute refers to is used. Temporary attributes with internal names are automatically created for long names and specific, named attributes are created by various VisualPQL and general SIR/XS commands including OPEN and SET ATTRIBUTE.

Binary Files

There are three formats that specify that binary data is being transferred. The 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.
The 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. For example, the following program copies any file:

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. The READ, WRITE and CLOSE commands may use an opened file.

Files are accessed by the READ and WRITE commands.

fileid	The internal name or attribute of the file is the name referenced by any READ, WRITE or CLOSE command. If the external filename is exactly the same as the attribute name and the file is in the default directory, the DSN may be omitted. Otherwise the DSN clause must be specified. If a member is being opened, this must be the member name. If the family name is not specified, the current default family name is used. If the procfile name is not specified, the current default procfile is used.
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 just 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 or record markers. To illustrate the differences between writing text and binary, suppose a write statement references an integer with a value of say 100. In the text file (with no format), this results in the characters 100 (in hexadecimal a character 0 is 30 and character 1 is 31 so this is 313030) but in a binary write (with format IB4) of an integer*4, this results in the hexadecimal 4 bytes value 64000000 (This is true on a PC but different byte ordering applies on other machines that gives different results). Similarly, if a binary file is read, the internal fields on the read must match the type of data being read. You must know what you are doing to use binary files!
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 single 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	Specifies that file attribute entry is not stored with the subroutine object code.
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: 0 Successful Open - 5 File locked (in use) - 6 File not found - 8 Access problem - 9 Miscellaneous problems The codes that apply to members are standard error message numbers and are: 439 Cannot form member name. 440 Member must be type text. 441 Family password mismatch. 442 Member password mismatch. 443 Cannot open procedure file. 444 Family not found. 445 Member found but replace mode not specified. 446 Member not found. 447 Cannot open scratch file to process member. 449 Procedure file already open in this retrieval.
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.
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.

CLOSE

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

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 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.:

[procfile.][family[/pword].]member[/pword]:type

READ  [ 'prompt_text'] I/O_list
      [ 'prompt_text'] I/O_list ...

READ  ( fileid [ERROR=label] [IOSTAT=VARNAME] [MEMBER] [DYNAMIC]) I/O_list

The 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.
It is recommended that this interactive read is not used. Use DISPLAY TEXTBOX instead.

The file READ reads from a file. Records are read from first to last sequentially, a new record being read each time a READ of the file is executed.

Input is read according to the i/o list and values read from the input are assigned to program variables.

If the file is a normal text file then fields from the file are translated into appropriate internal formats. Each read reads a single record.

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 just those fields specified are read.

If explicit OPEN and CLOSE commands are not used, the first time the READ is executed the file is opened and program termination closes the file. If the file cannot be opened successfully, an error message is displayed and the program stops executing.

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 may be specified that is gone to when an error condition is encountered on the READ. Return codes with any value other than zero are errors. When the program reaches end of file, this results in an error return code (-4) and 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 we read
END WHILE
END PROGRAM

Options

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.

Free-field formats

I* Integer

F* Real

E* Real, scientific notation

D* Real, double precision

A* String

Positional specifiers

IBw Binary integer, w digits(1,2 or 4)

RBw Binary real, w digits (4 or 8)

HEXCHARn Read hex codes as characters.

Delimited Input

Picture clauses

s digit, decimal point, plus or minus

a any letter

u any uppercase letter

l any lowercase letter

c any character

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 from 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

The text file or member WRITE creates a new file, appends to an existing file (with the APPEND option on the OPEN) or creates a new member and writes records to the end of the specified file each time the WRITE command is executed. Output is formatted according to the i/o list and assigns values from the program variables to the output.

The binary file WRITE creates a new file or appends to an existing file (with the APPEND option on the OPEN) and writes fields to the end of the specified file each time the WRITE command is executed. The exact values from the program variables are written to the output in the internal format of those variables if they are strings or if the binary formats are used: IB1, IB2 or IB4, IR4 or IR8, (Use IB4 for dates or times).

fileid	Specifies the name of the output file or member. This may be an attribute or filename. The filename STDOUT can be used when options such as NOEOL are required but output is still directed to the default output. The filename CGI specifies that, if the program is being used in CGI mode from a webserver, output is returned to the server (which means that it appears on the user's web page). If the program is run in normal mode, i.e. not from a webserver, then a file called sircgi.htm is created. The NOEOL option can be used with CGI
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. REPLACE Gives permission to overwrite an existing member.
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.

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.

Format specifications for date, time and categorical variables may be numeric or string. The data is automatically converted to a proper output string, if string specifications are used.

If an output format is not specified, the first format encountered is taken to apply to all previous fields without a format.

If no formats or a free-field (*) format is specified, the following defaults are used:

• Integers use an "Iw" format, where w is the minimum required to print the value.

• Floating point either use an "Fw.d" format, where "w" and "d" are adjusted to maintain significance up to 8 decimal places or the "E" (scientific) notation with 5 significant decimal digits, depending on the value written.

• Strings use an "A*" format that writes the number of characters in the string followed by a blank.

• Date, time and categorical variables are written as strings.

Picture clauses

Each digit can be represented by a "9", a "z", a "*" or a "$". "9" specifies that leading zeros are replaced by blank; "z" specifies that leading zeros are written; "*" specifies that leading zeros are replaced by "*"; "$" after an initial "$" character, represents a floating dollar sign where leading zeros are suppressed. If the field has a value of zero, a picture of all "9"s results in blanks and all "$"s results in a single "$" since all leading zeros are suppressed; if a single zero is wanted, specify a single "z" as the last character of the picture.
A period represents the decimal point and separates the specification into characters before and after the decimal point. There can only be one decimal point (period) 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.
Specify comma (,) to insert this character. If leading zeros are suppressed (by blanks or a floating dollar), any leading commas are suppressed. If a single dollar sign is specified, it is output in that position. If multiple dollar signs are specified, these suppress leading zeros and result in a floating dollar sign that is output in front of the first significant digit. After the decimal point, the special characters "9", 'Z', "$" and "*" are all equivalent and specify a digit. Any other characters are treated as any other special character.
Negative numbers, by default, 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.
The same picture specifications apply to the PFORMAT function. For example:

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

Dw.d Real double precision, w digits wide, d decimal places

Aw String, w characters wide

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')

Free-field formats

I* Integer

F* Real

E* Real, scientific notation

D* Real, double precision

A* String

CHARHEX* Write characters as hex 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 Print the next n elements of the previous array. n must be 1 or greater. 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.