HomeStartingEnvironmentDBMSVisualPQLProceduresSQLFormsHost/APIIndex
VisualPQL homecontents start chapter top of pagebottom of pagenext page index Reading and Writing Files

File Input & Output

VisualPQL provides access to operating system files.

Attributes

SIR/XS uses short (up to 32 characters), internal names known as attributes that map to long, fully qualified filenames (up to 240 characters). A specific file has a specific location and a file name may be fully qualified with path or subdirectory specifications. When VisualPQL accesses a file, it passes the name directly to the operating system without checking it for validity.

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'
READ ( MYFILE ) DATALINE (A20)
- reads the specific file using an attribute called MYFILE which is kept past the end of execution.

Reading and Writing Files

There are VisualPQL commands that read and write files.

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 Files

Normally, files read or written by explicit reads and writes in VisualPQL are text files; that is, they contain readable characters together with end of record characters and can be viewed with a text editor. VisualPQL can also read and write binary files using a combination of the 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.

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

homecontents start chapter top of pagebottom of pagenext page index

OPEN

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:-
Suppose a write statement references an integer with a value of 100. In the text file (with no format), this results in the three text characters 100 which is 313030 in hexadecimal (in hexadecimal, character 0 is 30 and character 1 is 31) but in a binary write (with format IB4) of an integer*4, this results in the 4 hexadecimal bytes 64000000 (This may differ on machines which are not Intel based). 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 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:

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.

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 LRECL value should be sufficient to accomodate the longest set of i/o specifications on a single READ or WRITE.

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

homecontents start chapter top of pagebottom of pagenext page index

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.

homecontents start chapter top of pagebottom of pagenext page index

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

homecontents start chapter top of pagebottom of pagenext page index

READ

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

Options

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.

homecontents start chapter top of pagebottom of pagenext page index

Input Format Specification

Fixed-field formats

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.

Positional specifiers

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.

Binary Formats

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.

Delimited Input

The free field input formats (represented by *) expect delimited input. Blanks, tabs and commas are delimiters and multiple blanks or tabs are treated as a single delimiter. Multiple commas are taken as multiple fields i.e. each comma corresponds to one field on the input. Two commas together in the data result in blank input to that field.
If the field is in quotes, then the string in the quotes is used (start and end quotes stripped off) and delimiter characters are ignored inside the quotes. Numeric input cannot be in quotes. If the input is not valid for the specified variable, the variable is set to undefined.

* 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

Picture clauses

Instead of a format, a picture clause enclosed in quotes can be specified. The picture specifies a fixed length field to read and must be the same length as the input. The picture must represent the expected input and can contain specific characters expected at particular places in the input together with predefined codes to indicate classes of characters. A picture can be specified for numeric and for string variables. The predefined codes can be upper or lower case and are :

C any character

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.

homecontents start chapter top of pagebottom of pagenext page index

READ - Interactive

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.

'prompt text' The text displayed on the screen to request input. Specifying prompt text or omitting a filename indicates that interactive input is expected. The text box is displayed with a single line for input. The maximum input size is 80 characters. Multiple fields may be read at once depending on the format specification. A second prompt may be specified on the single command that is essentially identical to repeating the command.

homecontents start chapter top of pagebottom of pagenext page index

REREAD

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

homecontents start chapter top of pagebottom of pagenext page index

WRITE

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 STDOUT as the fileid and 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.

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.

homecontents start chapter top of pagebottom of pagenext page index

I/O List - Output Specification

Fixed-field formats

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 Field formats

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

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 variable

I* Integer

F* Real

E* Real, scientific notation

D* Real, double precision

A* String

HEX* String

CHARHEX* String as hexadecimal codes.

The following defaults are used for free field formats:

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.

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

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:

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.

Each digit can be represented by "9", "Z", "*" or "$":
"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.

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:

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.

homecontents start chapter top of pagebottom of pagenext page index