Category:File Operations: Difference between revisions

File Types: Display, Internal And External

Business Rules differentiates between three different file types: display, internal and external. Each of these file types facilitates different kinds of programming tasks. This section provides a comparison of the different file types and should help you in determining which is the best file type for a particular task.

Communications files are not specifically addressed in this section because they are considered a type of display file. For information about the special characteristics of communications files, see the OPEN communications statement and Communications.

Cross platform I/O is now supported. This means you can read and write data and indexes on both Intel and Risc platforms from either platform.

Also see File Types Comparison for more information.

Long File Names

When you specify a file name or a font name there is a tendency to enclose it in quotes, especially if it contains embedded spaces. DON'T do so in OPEN statements.

In the case of file names, single quotes are permitted as part of the name such as 'Mary's letter to Jim'. BR forwards the fully quoted name to the operating system. If double quotes are used, Windows will reject the name as invalid. If single quotes are used they will be regarded as part of the name.

As for font names, the quotes are also passed to the operating system, in which case it won't find the font and will use the next best alternative (usually the default). No error is generated because BR doesn't know it is invalid until the window is opened, and font selection is quite forgiving.

The only time you should enclose a file name with embedded spaces in quotes in BR is for commands like COPY or DIR.

Display Files

Business Rules! uses display files to store procedures, source programs and the BRConfig.sys file. See also Open Display

Structure

Display files are standard ASCII text files. They can be modified with text editors and some word processors. Display files can be printer files, or streams of characters to be sent to a printer. Display files have variable-length records with an optional programmer-specified record delimiter (see OPEN display's EOL parameter for more information about this feature). The default record length for a display file is 132 characters (this is also true for most wide-carriage printers).

The record length in a display file has no impact on input processing. It is possible to input strings which are longer than the record length (provided the input variables are dimensioned large enough). On output, a string that is longer than the record length will be broken into records of 132 characters (or the specified record length).

Viewing the contents

The contents of a display file can be examined or displayed with Business Rules TYPE command.

Use with SORT and INDEX

Display files cannot be used as indexed files and cannot be sorted by Business Rules! built-in file sort. They can be sorted on by the AIDX and DIDX functions as used in the MAT statement (see MAT M in the statements and AIDX or DIDX for more information).

File I/O

Display files may be opened for either INPUT or OUTPUT. As OUTIN is not supported (except with communications files), display files can be difficult to update. Only the sequential access method is allowed on display files. The statements that can be used for input from display files are INPUT and LINPUT. Formatted input is not allowed. Output (either formatted or unformatted) to display files is accomplished with the PRINT statement.

Internal Files

For most business applications, internal files are the most frequently used type of file. See also Open Internal.

Structure

The first record of every internal file is a header record which "remembers" the record length and other important information about the file.

Each record after the header record begins with a system-controlled byte used to mark records for deletion (see the -D option of the Copy command for information about removing records marked for deletion). As long as internal files are always processed as internal files, the header record and the delete byte are transparent to the programmer. Internal files use fixed-length records with no record delimiter.

Viewing the contents

The best way to see the contents of an internal file with a Business Rules program is to read the file and print its information in a formatted report that is visually meaningful (e.g., a new line for each record, spaces between fields, special numeric formats converted to ASCII digits, etc.).

Although it is possible to use the Type command to view the full contents of an internal file, the output is often unreadable due to lack of record delimiters and the presence of unprintable (non-displayable) characters where special numeric formats such as packed decimal are used. External files are similarly unreadable, but display files may easily be viewed in their entirety.

Use with SORT and INDEX

Internal files are the only type of file that can be used with Business Rules SORT and INDEX (ISAM) facilities. Data which is used for input to either the SORT or INDEX commands must be stored in internal files. Likewise, SORT or INDEX output files and the sort control file must be internal files.

File I/O

Internal files may be opened for INPUT, OUTPUT and OUTIN (which is a combination of input and output). Individual records or portions of individual records are easily updated by opening the file OUTIN. Sequential, relative, or keyed access methods can be used.

The statements that can be used for input from internal files are READ and REREAD. Output to internal files is accomplished with the WRITE and REWRITE statements. Records can be marked for deletion (made inactive) with the Delete Statement. The RESTORE file statement can reposition the file pointer to the beginning of the file or to a specified record.

Internal files provide several space-saving formats for storing numbers including binary (BB Format Specification), double- precision floating point (DD Format Specification), single-precision floating point, packed decimal (PD Format Specification), zoned decimal (ZD Format Specification), and (for S/23 compatibility only) long numeric floating point (LL Format Specification). See Format Specifications for more information about these and other formats that are available with internal files.

Version 3.9+ enables NFS and NetBui network record and file locks up to 2GB. However, versions 4.13+ supports larger files (exceeding 2GB) when OPTION 33 is specified. These larger files are NOT supported by NetBui which uses 30 bit record locking. Therefore use the client server model if you need to use NetBui with large files. See BRConfig.sys and Record Locking for more information.

Linked Files

Business Rules now supports LINKED files, which are Business Rules internal files that contain one or more sets of linked records. When their use is appropriate, linked files can be much faster than indexed files (probably two to three times as fast), and they require less overhead.

Program performance does not degrade when they increase in size. Also, records may be inserted at any point in a linked list.

However, two potential drawbacks are that corrupted link list files can be difficult to rebuild in the correct order. Also, there is no way to identify the order in which linked records are added to the file because of the way the system handles deleted records in linked list files.

Linked files are most useful for situations where you wish to attach a group of records to a master record, and the only way you will ever want or need to access those records is through the master record. An example usage is a customer maintenance program that allows the user to keep notes (up to 15 lines of 50 characters each) about each customer.

The following terms will be used to describe the operation and structure of linked files:

1.) {\b Linked file} - A file that is opened LINKED, INTERNAL. This file will ultimately contain one or more linked lists.

2.) {\b Linked list} - An entire set of linked records. A single linked file will usually contain several linked lists.

3.) {\b Linked list record} - Any record in a linked list, regardless of its position within that list. The first eight bytes of each linked list record are reserved for two fields:

(a) The next record pointer (positions 1-4)

(b) The previous record pointer (positions 5-8).

These are maintained by Business Rules and must not be overwritten by the program. While they are normally ignored, the program can access them with a statement such as the following:

00100 READ #1,USING "FORM 2*BH 4":NEXTPTR,PREVPTR

Next record pointer - Positions 1 through 4 of each linked list record, which identify the next record in the linked list. If this pointer is set to 0, the record is the last one in the linked list. This pointer position is maintained by Business Rules and must not be overwritten by the program.

Previous record pointer - Positions 5 through 8 of each linked list record, which point to the previous record in the linked list. If this pointer is set to 0, the record is the first one (the anchor record) in the linked list. This pointer position is maintained by Business Rules and must not be overwritten by the program.

ANCHOR RECORD

The first record in a linked list, and the basis for accessing linked list data from the master record. The record number of this anchor point should always be written out to the master file after the list is updated. (If an anchor record has been processed, KREC will return the record number of the anchor record for the current linked list, even if the file pointer is positioned at another record in that list.) The previous record pointer (positions 5-8) of an anchor record will always be set to 0.

RELATED RECORD

The second and additional records in a linked list. The last record in a linked list will have a next record pointer of 0.

The following Business Rules instructions play important roles in the use of linked files:

OPEN INTERNAL STATEMENT

OPEN internal now accepts the LINKED keyword, which specifies that the file to be opened consists of linked lists.
Also see Open Internal

RESTORE FILE STATEMENT

In linked files, the RESTORE file statement plays two important roles.

1.) It can be used with the REC= parameter to reposition the file pointer to any specified record number.

2.) The next role of RESTORE is that it can be used without parameters to create a new anchor point for a linked list that you wish to add or insert.

Also see Restore File

READ FILE STATEMENT

The READ file statement now accepts the LINK=string parameter for Verifying that linked records belong to a master. It can be used only on LINKED files that have been opened using the KPSI7E4W2= and KLNE2E4W2= parameters
Also see Read file.

WRITE STATEMENT

The WRITE statement may be used to insert a record into an existing linked list. (A linked list is not considered to be "existing" unless an anchor point has been established for it with a RESTORE statement.)
Also see Write.

DELETE STATEMENT

The DELETE statement may be used to delete any anchor record or sub-record from a linked list. If REC= is not specified, the DELETE statement must be preceded by a successful READ of the record to be deleted.
Also see Delete Statement.

KREC(filenbr) function

KREC will return the record number of the most recently processed (read or written) anchor record.
Also see Krec(filenbr) in the Functions section.

LINKED ERROR CODES

The following error codes are specific to LINK. For full descriptions see each code individually.

4282 Data does not match LINK=

4283 Error in updating previous/next link

0606 Invalid element in OPEN

0702 File not opened KEYED or LINKED

0718 Key length conflict

External Files

External files allow programs to access files used by other languages or database and spreadsheet packages. See also Open External.

Structure

When a file is opened for external processing, Business Rules can read, write and position to any byte in the file-no matter what its structure.

Business Rules assumes very little about the structure of an external file. It treats the file as if it has no header record and as if it has no record delimiter. If these items do exist, the program and the file I/O must account for them.

Files that were originally created as internal or display files can be opened as external. If a file created as an internal file is later processed as an external file, however, the delete byte and header record must be taken into account.

Viewing the contents

The best way to see the contents of an external file is with a Business Rules to read the file and print its information in a formatted report that is visually meaningful (e.g., a new line for each record, spaces between fields, special numeric formats converted to ASCII digits, etc.).

Although it is possible to use the TYPE command to view the full contents of an external file, the output is often unreadable due to lack of record delimiters and the presence of unprintable (non-displayable) characters where special numeric formats such as packed decimal are used.

Use with SORT and INDEX

External files cannot be used as indexed files and cannot be sorted by Business Rules built-in file sort.

File I/O

External files may be opened for INPUT, OUTPUT and OUTIN. Individual records or portions of individual records are easily updated by opening the file OUTIN. Sequential or relative access methods can be used.

The statements that can be used for input from external files are READ and REREAD. Output to external files is accomplished with the WRITE and REWRITE statements. The RESTORE statement can move the file pointer to the beginning of the file or to any specified record or byte. The DELETE statement cannot be used on external files.

Business Rules will transmit data to or from external files in all the same formats that it will use with internal files. However, it is the responsibility of the programmer to ensure that any data output to an external file remains in a format that is compatible with the overall intent of the file.

Whenever an external file is opened, a record length must be specified. Business Rules then treats the file as if it has that fixed record length. Every input or output operation affects the specified number of bytes. If RECL equals 50, for example, a read from byte 47 would automatically bring in bytes 47-96. The RLN function may be used to shorten the record length of an external file after it has been opened.

File Processing: New, Use, Replace Parameters

The NEW, USE and REPLACE parameters, along with an independent default, are available in the Business Rules display, OPEN internal and OPEN external statements. These parameters indicate whether the file being opened is to be newly created or whether it should be an existing file. This section describes the actions of each of the four options. Each of the four options (NEW, USE, REPLACE and the default) follows a two-level action plan, as described in the chart below:

In short, the USE and REPLACE parameters will open a file whether the file already exists or not. Errors will be generated by NEW and by the default of using the old file if their first action is unsuccessful. These errors (4150 and 4152) can be trapped using the IOERR error condition. IOERR may either be coded at the end of the OPEN statement or in an ON IOERR statement that gets executed before the OPEN statement.

The following paragraphs describe each of the four options in detail:

DEFAULT

When the default is selected, Business Rules attempts to use an existing file. If the specified file does not exist, error code 4152 results. Selecting the default is different from selecting the USE parameter in that USE will create a new file (rather than generate an error) if its attempt to open an existing file fails.

NEW

When the NEW parameter is specified, Business Rules attempts to create a new file. If a file under the specified name already exists, the attempt will fail and error code 4150 will result.

USE

When the USE parameter is specified, Business Rules attempts to use an existing file. If an existing file by the specified name does not exist, however, Business Rules creates a new file.

REPLACE

When the REPLACE parameter is specified, Business Rules first attempts to create a new file. If this is unsuccessful because a file by the specified name already exists, Business Rules will free the existing file and then create a new file under the same name. Business Rules will not warn the user that it is replacing an existing file when REPLACE is used.

I/O with the TRANSLATE= parameter

The TRANSLATE= parameter is available in four of the Business Rules OPEN statements (for display, internal, external and communications files). This optional parameter allows the translation of data to or from another collating sequence.

About Collating Sequence

Internally, all computers represent letters of the alphabet, punctuation marks and even digits according to an arbitrary numbering scheme. Two of the most popular coding schemes are ASCII (American Standard Code for Information Interchange) and EBCDIC (Extended Binary Coded Decimal Interchange Code). Probably the most common use of the TRANSLATE= capability is translating files between ASCII and EBCDIC.

An example of the difference between ASCII and EBCDIC is that the uppercase letters A, B and C are represented by 65, 66 and 67 respectively in ASCII; but in EBCDIC, they are 193, 194 and 195. Also, in ASCII, the blank or space character is represented by the number 32 while in EBCDIC it is number 64. Although all systems that currently run Business Rules the ASCII coding scheme, some computer systems (including most IBM mainframe computers) use EBCDIC.

Enhancements

Cross platform I/O is now supported. This means you can read and write data and indexes on both Intel and Risc platforms from either platform.

Files larger than 2GB are supported. The maximum file size is 4611,686,018,427,387,903 bytes. This will handle a lot of recipies.

OPTION 33 must be on to invoke this feature. It has been tested using TCP/IP only. We expect NetBui and some versions of IPX to fail above 2GB. This option will fail in Windows 95, 98 and ME.

OPTION 33 is now supported in Linux. Therefore we will be numbering Linux releases ending with the digit 3 (e.g. 4.03, 4.13).

Format Specifications

Format specifications tell Business Rules the form that a particular data field will be in. A format specification is required whenever data is input into or output from a program. It is also required with the full screen processing statements. Format specs are not required in the following situations: with unformatted internal files, with all display files, and when unformatted PRINT statements are used.

Not all format specifications are alike in their uses. Some can be used with internal and external files, but not with display files. Some can be used only with full screen formatting. And some format specifications behave differently depending on whether they are used for input or output.

B Format Specification

The B (binary) format specification is used for fast and efficient internal numeric storage. Binary format is machine specific. There are two types: BH stores the most significant byte first, and BL stores the least significant byte first. B format defaults to BH or BL, whichever is the native format of the hardware. When portability is desired, BH or BL should be used. When speed is desired, B should be used. In general, systems that utilize Intel chips will use a native format of BL, and those that don't will use BH. The following chart indicates the format native to several hardware/operating system combinations:

COMPUTER	NATIVE FORMAT
AT&T with UNIX	BH
IBM PC, XT, AT, with DOS	BL
IBM AT with LINUX	BL
NCR Tower with UNIX	BH

The field length for a B-formatted number can be 1, 2, 3 or 4. The value range for each field length is as follows:

FIELD	VALUE
LENGTH	RANGE
1	+ / - 127
2	+ / - 32, 767
3	+ / - 8, 388,607
4	+ / - 2, 147, 483, 647

Technical Considerations

1.) As with ZD and PD, the decimal point is implied for B format specifications; it is not stored with the number. To retrieve the same number as was written, the same format specification must be used. Reading a field with a B 4 that was written with a B 4.2 results in a number 100 times larger than was written. The number is rounded to the specified number of decimal positions before writing.

See Also

The letter B can also be used as a screen attribute for string or numeric values. See the category, field specifications. B is also used in PIC

BL Format Specification

The BL (binary low) format specification is used for fast and efficient numeric storage. It is different from B and BH in just one way: when BL is specified, the lowest byte is stored first (BH stores the highest byte first, and B defaults to either BL or BH according to the native binary format of the hardware that Business Rules being run on).

See also the B format specification discussion.

BH Format Specification

The BH (binary high) format specification is used for fast and efficient numeric storage. It is different from B and BL in just one way: when BH is specified, the highest byte is stored first (BL stores the lowest byte first, and B defaults to either BL or BH according to the native binary format of the hardware that Business Rules is being run on).
(See also the B format specification discussion.)

C Format Specification

The C (character) format specification identifies string data. It can be used with both types of FORM statements (for internal/external files and for display files), and it can be used with the full screen processing statements.

Input characteristics

For string input, C format specification retains all trailing spaces when reading in a value with a specified field length. If the field length is not specified, the field length defaults to the maximum dimensioned length of the variable.

Output characteristics

When C is used for output, the string value is printed with blanks padded on the right (leading spaces are retained), as in the following example:

00010 PRINT USING 20:"ABC","DEF"
00020 FORM C 8,C 3

Output from the above example prints to the screen as:

ABC   DEF

If the field length is not specified, the field length defaults to the current string length (the value from the LEN function) of the variable, as in the following example:

00010 PRINT USING 20:"ABCDE","fgh"
00020 FORM C,C

Output from the above example prints to the screen as:

ABCDEfgh

Technical Considerations

1.) When used for string output, the C, V and G specifications behave identically. On string input, V and G differ from C in that they remove all trailing spaces.

The following example illustrates reading the same string three different ways:

00010 READ #1,USING 20: A$
00020 FORM C 18
00030 REREAD #1,USING 40: B$
00040 FORM V 18
00050 REREAD #1,USING 60: C$
00060 FORM G 18
00070 PRINT USING 80: A$, LEN(A$),LEN(B$),LEN(C$)
00080 FORM C 20,3*N 5

This example outputs the following:

12345         18  5  5

The output indicates that the string length (determined by the LEN function) is shorter for the strings read with the V and G specification. Input is the same for all three.

2.) See the CC Format Specification, CR Format Specification, CL Format Specification and CU Format Specification format specifications for information on the variations of C.

See Also

The letter C can also be used as a control attribute to control cursor position upon entering the screen.

CC Format Specification

The CC (character, centered) format specification identifies string data that is to be centered upon output. It can be used for both types of FORM statements and with the full screen processing statements.

Input characteristics

When CC is used for input, it is treated the same as C is on input. (See C Format Specification for more information.)

Output characteristics

When CC is used for output, Business Rules all leading and trailing spaces, then evenly pads spaces to the left and the right of the value according to the amount specified as the field length. If field length is not specified, the default field length is the length of the string (including spaces); CC centers the value within this amount.
The following example will center the text on the second line of the screen:

01000 PRINT FIELDS "2,1,CC 80": "Payroll"

When padding of an odd number of characters is required (such as when a value with an even number of characters is centered in a field with an odd-numbered field length); extra padding goes to the right. NOTE the following example:

00050 PRINT USING "FORM CC 6": "ABCD"
00060 PRINT USING "FORM CC 6": "ABC"

The output from the above lines would look as follows:

ABCD
ABC

C for centered is a Control Attribute

CL Format Specification

The CL (character, lowercase) format specification identifies string data that is to be converted to lowercase upon keyboard input. It can be used with INPUT FIELDS and RINPUT FIELDS processing. (PRINT FIELDS accepts it and treats it the same as C. If it is specified with FORM, error 1006 will be generated.)

Input characteristics

When CL is used with keyboard input, case conversion automatically occurs as characters are being typed in. Even if the operator attempts to type uppercase letters, only lowercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally -by a CL specification.

The following example will convert all letters entered to lowercase:

00100 INPUT FIELDS "1,40,CL 10,r": X$

Output characteristics

When CL is specified for output in any of the full screen processing statements, it is treated the same as C (see the C Format Specification for more information). CL cannot be used for either input or output in a FORM statement.

See Also

The letter L can also be used as a Control Attribute.

CL is short for the CLOSE statement and the CLEAR command.

CR Format Specification

The CR (character, right justified) format specification identifies string data which is to be right justified upon output. It can be used with both types of FORM statements and with the full screen processing statements.

Input characteristics

When CR is used for input, it is treated the same as C is on input. (See the C format specification discussion for more information.)

Output characteristics

When CR is used for output, Business Rules all leading and trailing spaces, and then right justifies the string according to the value specified as the field length. If the field length is not specified, the default field length is the length of the string (including spaces); CR right justifies the value within this amount.

In the following example, lines 1100 and 1200 will print text flush against the right edge of the field so that the two colons will both appear in column 20 of the screen:

01100 PRINT FIELDS "6,2,CR 19": "Enter Date:"
01200 PRINT FIELDS "9,2,CR 19": "Enter Employee ID#:"

See Also

The letter R can also be used as a Screen or Color Attribute.

The letters CR can also be used as a PIC insertion character.

CU Format Specification

The CU (character, uppercase) format specification identifies string data that is to be converted to uppercase characters upon input. It can be used with INPUT FIELDS and RINPUT FIELDS processing on internal files. (PRINT FIELDS accepts it and treats it the same as C. If it is specified with FORM, however, error 1006 will be generated.)

Input characteristics

When CU is used with keyboard input, case conversion automatically occurs as the characters are being typed in. Even if the operator attempts to type lowercase letters, only uppercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally -by a CU specification.

The following statement will convert all letters entered to uppercase:

00100 INPUT FIELDS "1,40,CU 10,r": X$

Output characteristics

When CU is used for output with either PRINT FIELDS or RINPUT FIELDS, it is treated the same as C (see the C Format Specification for more information). CL cannot be used for either input or output in a FORM statement.

D Format Specification

The D (double-precision floating-point) format specification should be used where speed and/or floating point are required. All numbers internal to Business Rules stored in this format, so almost no effort is required for Business Rules read or write D format.

D can be used with FORM for internal and external files. It is not available with FORM for display files and it cannot be used with full screen processing.

Input characteristics

Since D represents a floating-point number, any number with any amount of decimal positions will be accepted when D is specified. Rounding will not occur. A field length or number of decimal positions is never specified when D is coded. Business Rules eight characters of storage for every D-formatted data item.

Output characteristics

All significant digits in D-formatted data will be output exactly as they were input.

Technical Considerations

1.) By definition, D is not portable. It is native to the floating-point format of the machine.

2.) D may be compatible with non-Business Rules, specifically "C" files.

3.) D is machine dependent, but all machines should support 10e+-307 with up to 15 digits of precision.

See Also

The letter D is also used as a PIC insertion character.

DT, DH and DL Format Specification

The DT, DL, and DH format specifications

DT 3 or DT 4
DL 3 or DL 4
DH 3 or DH 4

Description

These utilize binary storage formats corresponding to B, BL and BH. They also perform days() processing utilizing the "current" default date format (mdy/ ymd/ dmy etc.). These formats are intended to reduce the number of changes required for Y2K compliance, and to ease ODBC access to dates stored in 'day of century' format. However, ODBC also has a much more comprehensive date identification scheme.

Technical Considerations

1.) The DAYS() function permits four digit years even if C is not specified in the mask statement.

2.) When days() or DH is used to store a date, normal sorting and indexing becomes Y2K compliant. The days() function, and the date formats eliminate the need for BASEYEAR processing when the values are stored in binary fields. These can subsequently be indexed as character fields so long as they were stored in high-to-low order.

FMT Spec

The FMT format specification is supported for use with FIELDS processing for validating and formatting of entered string or numeric data. It is similar to PIC as used for screen I/O, but more powerful, and more suited to use with strings.

One of the advantages of FMT is that it handles simple error checking of entered data (beeping when any character entered is in the wrong format) and it can fully format a field for input by forcing uppercase/lowercase, flush right and zero fill formatting. Another advantage is that it can display a single field (from the programmer's perspective) as two or more fields for the user.

Similarly, as of 4.3, #FMT can be used to work with numeric values from a string. Similar to #PIC and #G, #FMT indicates that string data should be processed numerically. This works for INPUT FIELDS as well as GRIDs and LISTs.

For example: #FMT(###.##), when used in conjunction with the strings "231.45", "430", etc.

Input And Cursor Characteristics

The first field specification in the following example displays to the user what looks and acts like two fields which are separated by a dash. Insert, delete, erase and field plus will modify only one part of the field. Pressing the down arrow will move the cursor from any position in the first part to the first position in the second part.

However, when the cursor is positioned at the first field after the field specified by a FMT spec (at row 12, column 10 in the following example), pressing the up arrow will cause the cursor to move to the first position in the first part of the FMT field.

Only numeric data will be allowed, even though the entered value is to be assigned to a string Variable. A beep will sound if an invalid character is typed for any position. Once entered, the data will be right justified.

00100 INPUT FIELDS "10,10,FMT(R999-R9);12,10,C 12,AE":X$,Y$

Examples

The following INPUT FIELDS statement will display two field parts separated by a dash.

1.) The first field part will accept any character, leaving case as entered. It will also be right justified upon field part exit.

2.) The second field part will accept any character but force it to uppercase if alphabetic. No right flush formatting will be done on field exit.

00200 INPUT FIELDS "10,10,FMT(RXXX-XXX),AE":X$

The next INPUT FIELDS statement displays two field parts separated by a dash. The first four characters must be alphabetic, and they will be forced to uppercase. The second four characters must be numeric.

If fewer than four characters are entered, the entered data will be right justified and, within the second group of four characters. Positions to the left of the first entered character will be filled with zeros.

00200 INPUT FIELDS "10,10,FMT(RAAA-#999),AE":X$

Examples of values that could be entered for the above code fragment are as follows:

ABCD-1234
ACB-0001
B-1000

FMT Vs PIC

With some exceptions, FMT is best suited to handling strings, whereas PIC is generally used with numeric data only. See the chart below comparing the two:

FMT Syntax

The FMT spec can be used in the same places that PIC is allowed in INPUT FIELDS, RINPUT FIELDS and PRINT FIELDS statements. The FMT keyword must be followed by up to 40 character identifiers and/or insertion characters.

Character identifiers tell the system which characters are allowed in the current position, and they identify the way in which the data part should be formatted for input. (Business Rules considers any section of a FMT spec, which is separated from other sections by one or more insertion characters to be a data part.) The following character identifiers are currently available:

9	Allow any number from 0 to 9.
a	Allow any character from A to Z or a to z, and leave case as entered.
G	Allow any character from A to Z, a to z, or 0 to 9, and force it to upppercase if its alphabetic.
g	Allow any character from A to Z, a to z, or 0 to 9, and force it to lowercase if its alphabetic.
P or p	Protected. Business Rules will not allow the cursor to rest on or change any data that is displayed in this position
R	Mimic the next character specification. Right flush this part from current position to the end of this part (preceding next R or #), process according to the next character identifier within this part (if R is the only character type used, error 0805 will result).
X	Allow any character and force to uppercase if its alphabetic.
x	Allow any character and force to lowercase if its alphabetic.
Y	Allow only Y, y, N, or n, and force it to uppercase.
y	Allow only Y, y, N, or n, and force it to lowercase.
#	Mimic the next character specification. Right flush and zero fill from current position to end of this part (preceding next R or #), process according to the next character identifier within this part (if # is the only one used, error 0805 will result).

Insertion characters are displayed exactly as they appear in the FMT specification. Business Rules treats any keyboard character that is not a character identifier (listed above) as an insertion character.

Insertion characters are inserted for the operator's benefit. They will not be in the data. Note that "P" can be used to protect characters that you want to appear in the data.

G Format Specification

The G (generic) format specification identifies data that may be either data or string. This is a highly versatile format specification, as it can be used with both types of FORM statements (for internal/external files and for display files), and the full screen processing statements.

Conversion errors on G, N, and PIC formats can now be avoided on output to display files when the CONV=parameter is used in the OPEN DISPLAY statement. Also when CONV=is used, PIC processing will first try removing the commas from the output if doing so will prevent an overflow condition. See the OPEN DISPLAY Statement for more information concerning CONV=.

N and G lengths are limited to 127.

Input characteristics

The input characteristics of G differ according to whether it is used with string or numeric data. When used with string data, G operates the same as V in that it removes all trailing spaces. G is the same as N when used with numeric data. The field length for a G or N specification must identify the leading minus sign if needed, and a decimal point and decimal places if specified. Fraction length is optional and indicates the number of decimal places to be printed. The value will be rounded to the number of decimal places specified.

Output characteristics

The output characteristics of G differ according to whether it is used with string or numeric data. When used with string data, G formats output in the same way that C and V do. Data is printed on the left side of the output field (leading spaces are retained) and padded with blanks on the right.

NOTE the following example including the space ahead of the letter A

00010 PRINT USING 20: " ABC","DEF"
00020 FORM G 8,G 3

Output from the above example appears as follows:

 ABC    DEF

Notice that the first string value is output with one leading space, as was specified in the PRINT statement.

When used for output of numeric data, G is identical to N. Numeric values are right-justified, padded with blanks on the left, and rounded to the specified number of decimal positions.

The following example uses the format specification G 6.2 to format 50.5 and output it to the screen. The total length of the field, including the leading blank and decimal point, is 6:

00010 PRINT USING 20: 50.5
00020 FORM G 6.2

Output from the above example would be as follows (note that there is one leading blank; the output is right justified in the field length specified):

 50.50

Technical Considerations:

1.) See the C format specification for an example of the differences between C, V and G format specifications.

2.) See the GF, GL, GU, and GZ Format Specifications for information on variations of the G specification.

3) As of 4.3, #G can be used to work with numeric values from a string similar to #PIC and #FMT, which indicates that string data should be processed numerically for display and sorting purposes. This works for INPUT FIELDS as well as GRIDs and LISTs and it works for all variants of the G format.

See Also

The letter G can also be used as a Control Attribute.

G is also an FMT character identifier, meaning display any character from A to Z, a to z, or 0 to 9, and force it to upppercase if its alphabetic. See FMT Syntax. Lowercase "g" means the same except forced to lowercase.

GF Format Specification

The GF (generic floating-point) format specification has been added for use by the FORM statement and by the INPUT / PRINT FIELDS. It is the same as G in that it can be used with either string or numeric data and in all other ways it is identical to L as used with INPUT and PRINT FIELDS. Note the following code fragment:

00100 PRINT USING " 2*GF 10":333,444.44

Outputs

333 444.44

GF left justifies strings and right justifies numbers. Strings may be any value not exceeding the specified length. Numbers may include a decimal point at any position and may have an exponent.

The following program demonstrates this:

00010    open #1: "name=xxx,recl=80,replace",internal,outin,relative 
00020    write #1,using 'form gf 10,c': 1234.56,"X"
00030    write #1,using 'form gf 10,c': "1234.56","X"
00040    write #1,using 'form gf 14,c': 123456e-20,"X"

This program produces a file with three records containing the following, where "bbb" represents three blank spaces:

bbb1234.56X
1234.56bbbX
bbb1.23456E-15X   (the normalized form of the value)

See Also

The letter G can also be used as a Control Attribute.

GL Format Specification

The GL (generic, lowercase) format specification indicates that string data is to be converted to lowercase upon keyboard input. It can be used with INPUT FIELDS and RINPUT FIELDS processing. (PRINT FIELDS accepts it and treats it the same as G. If GL is specified with FORM, error 1006 will be generated.)

Input characteristics

When GL is used with keyboard input of string data, case conversion automatically occurs as the characters are being typed in. Even if the operator attempts to type uppercase letters, only lowercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally - by a GL specification. When used for input of numeric data, GL operates the same as G.

The following example will convert all letters entered to lowercase:

00100 INPUT FIELDS "1,40,GL 10,r": X$

Output characteristics

When GL is used for output in PRINT FIELDS or INPUT FIELDS statements, it is treated the same as G (see the G format specification for more information). GL cannot be used for either input or output in a FORM statement.

See Also

The letters G and L can also be used as a Screen Attributes.

GU Format Specification

The GU (generic, uppercase) format specification indicates that string data is to be converted to uppercase upon keyboard input. It can be used with INPUT FIELDS and RINPUT FIELDS processing on internal files. (PRINT FIELDS accepts it and treats it the same as G. If it is specified with FORM, error 1006 will be generated.)

Input characteristics

When GU is used to input string data, case conversion automatically occurs as the characters are being typed in. Even if the operator attempts to type lowercase letters, only uppercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally -by a GU specification. When used with input of numeric data, GU operates the same as G.

The following example will convert all letters entered to uppercase:

00100 INPUT FIELDS "1,40,GU 10,r": X$

Output characteristics

When GU is used for output in PRINT FIELDS or RINPUT FIELDS statements, it is treated the same as G (see the G format specification for more information). GU cannot be used for either input or output in a FORM statement.

See Also

The letter G can also be used as a Control Attribute.

GZ Format Specification

The GZ (generic, zero suppression) format specification indicates that numeric values of zero are to be suppressed on output. GZ can be used with FORM statements for internal, external and display files, and it can be used with the full screen processing statements.

Input characteristics

When used for input, GZ is treated as G.

Output characteristics

When used for output of numeric data, GZ operates the same as NZ. If the value of a number is zero, blanks are output instead. If the value of a number is not zero, output is like N format. Printed values are right justified, padded with blanks on the left and rounded to the specified number of decimal points.

Output from the following example would be a blank line:

00010 PRINT USING 20: 0
00020 FORM GZ 4.2

GZ can efficiently take the place of simple PIC constructions. The following two lines are equivalent except that the first is shorter to code, it stores more efficiently and it executes more quickly:

00010 PRINT USING "FORM GZ 10.2,GZ 10": A,B
00020 PRINT USING "FORM PIC( - - --. -), PIC( - - - - -)": A,B

See Also

The letter G can also be used as a Control Attribute.

L Format Specification

The L (long) format specification is used for System/23 compatibility only. It identifies a double-precision floating-point number that uses 9 characters of storage space. L may be used with Form for internal or external files; it may also be used with full screen processing.

Input characteristics

When L is used with FORM for internal and external files, it is identical to the D format spec except that L requires nine characters of storage (D requires only eight). When L is used for input with full screen processing, the field length must account for a leading minus sign and decimal point if needed. Fraction length is optional. Numbers are not redisplayed (with the specified number of decimal places) when editing a field. L will retain extra decimal positions if they are entered and if the specified field length allows for them.

Output characteristics

All significant digits in L-formatted data will be output exactly as they were input.

Technical Considerations

1.) By definition, L is not portable; it is native to the floating-point format of the machine.

See Also

The letter L can also be used as a Control Attribute.

N Format Specification

The N (numeric display) format specification converts a number between its internal format (a bit pattern) and an ASCII character format (a number readable by humans). N is a highly versatile format specification. It can be used with the FORM statements for internal, external and display files, and it can be used with the full screen processing statements.

Conversion errors on G, N, and PIC formats can now be avoided on output to display files when the CONV=parameter is used in the OPEN DISPLAY statement. Also when CONV=is used, PIC processing will first try removing the commas from the output if doing so will prevent an overflow condition.

Input characteristics

When N is used for input, the field length must account for a leading minus sign if needed, and a decimal point and decimal places if specified. Fraction length is optional and indicates the number of decimal places to be printed. With INPUT FIELDS and RINPUT FIELDS, the actual number that is input will be rounded to the number of decimal places specified.

Output Characteristics

Numeric values output with the N format specification will be right justified, padded with blanks on the left, and rounded to the specified number of decimal positions. The following example uses the format specification N 6.2 to format 50.5 and output it to the screen. The total length of the field, including the leading blank and decimal point, is 6:

00010 PRINT USING 20: 50.5
00020 FORM N 6.2

Output from the above example would be as follows (NOTE that there is one leading blank; the output is right justified in the field length specified):

 50.50

Technical Considerations

1.) The G format specification performs identically to N when it is used with numeric data, but it may be specified when data may be either string or numeric.

2.) See the NZ (and GZ) format specifications for information about suppression of zero values on output of numeric data.

3.) See PIC Format Specification for additional options on formatting numbers (floating $, inserting commas and other punctuation, etc.).

In Open Window Statements

"N=attributes" is a parameter in Open Window statements which identifies the attributes that are to affect the entire inner portion of the window. However, the attribute specified takes effect only after a PRINT NEWPAGE has been sent to the window. The B (blink) attribute is not available for this parameter.

See Also

The letter N can also be used as a screen attribute.

NZ Format Specification

The NZ (numeric display, zero suppression) format specification indicates that numeric values of zero are to be suppressed on output. NZ can be used with FORM statements for internal, external and display files, and it can be used with the full screen processing statements.

Input characteristics

When used for input, NZ is treated as N. (See the N format specification discussion for more information.)

Output characteristics

When both are used for output of numeric data, NZ operates the same as GZ. If the value of a number is zero, blanks are output instead. If the value of a number is not zero, output is like N format. Printed values are right justified, padded with blanks on the left and rounded to the specified number of decimal points. If you want leading zeros to print (not be suppressed), use PIC (###).

Output from the following example would be a blank line:

00010 PRINT USING 20: 0
00020 FORM NZ 4.2

NZ can efficiently take the place of simple PIC constructions. The following two FORM statements are equivalent except that the first is shorter to code, it stores more efficiently and it executes more quickly:

00010 FORM NZ 10.2,NZ 10
00020 FORM PIC( - - --. -) PIC( - - - - -)

PD Format Specification

The PD (packed decimal) format specification is commonly used to save space in numeric storage. It is also used for maximum portability between computers. It can be used only with FORM statement for internal and external files.

Input Characteristics

When PD is used for disk input, a decimal point is inserted to the right of the specified number of digits in the memory representation of the value. Since the decimal point is not stored with a PD- formatted number (it is similarly only implied with ZD- and B-formatted numbers), the same format specification must be used to retrieve the number as was used to write it. Reading a field with a PD 5 that was written with a PD 5.2 results in a number 100 times larger than was written.

Output Characteristics

When PD is used for numeric output, the number is rounded to the specified number of decimal points before writing (like all numeric formats). Business Rules "packs" two numeric digits into each stored character (except for the last stored character, which will hold one digit and the sign). A PD field will hold 2*L-1 numeric digits, where L is the field length.

The range for a PD 5 is +/- 999,999,999. The last 4 bits of the field will be either F or C (hex) for a positive number or D (hex) for a negative number. For example:

00010 WRITE #1,USING 20: 22.5, -22.5
00020 FORM 2*PD 3.1

The above outputs the following six bytes to the disk in hexadecimal notation:

 	00 22 5F 00 22 5D

See also

PD 4

PIC Format Specification

PIC({Z|#|$|*|+|-|^|B|D|CR|DR|DB|,|.}[...])

The PIC format specification converts a number into characters according to the "picture" specified within parenthesis. The "pic-spec" parameter consists of PIC() and one or more characters, which are either insertion characters to be printed as is, or digit identifiers to be replaced with a digit when printed.

PIC may be used with both types of FORM statements (for internal and external files or for display files), and may be used with full screen processing statements. Unlike all other format specifications, PIC has its own set of specifications. These specifications generally fall into two groups: digit identifiers and insertion characters.

As of 4.3, #PIC can be used to process numeric data from a string variable. Similar to #FMT and #G, #PIC indicates that string data should be processed numerically. This works for INPUT FIELDS as well as GRIDs and LISTs.

For example, when used in conjunction with the strings "231.45", "430", etc.:

#pic($##,##0.00-)

will be able to use the numeric values.

Digit identifiers

Digit identifiers indicate that the position they mark should be replaced with digits on output. The symbols that operate as digit identifiers include Z, #, $, *, -, +, ^, ( and ). In some cases (as noted in the following descriptions), these characters act both as digit identifiers and as insertion characters.

Z

The Z (zero suppress) identifier is used to suppress a digit of zero. Zs that are placed to the left of the decimal point will suppress zeros on a digit-by-digit basis. In the following example, the left-most zero is suppressed but the next four are printed:

00010 PRINT USING 20: 000.00
00020 FORM 2*PIC(Z##.##)

The output from this example would be as follows:

00.00

If Zs are to have any effect on the right side of the decimal, all specified positions to the right must contain a Z. Suppression will occur only when the value of the entire number to be output is zero and, in such a case, a blank value will be output. The Zs to the right of the decimal will take precedence over any other digit identifiers or insertion characters in the PIC specification. Output from the following example would be a blank line:

00010 PRINT USING 20: 000.00
00020 FORM PIC(###.ZZ)

#

The # identifier is used for zero fill, for example:

00010 PRINT USING 20: 1000,0
00020 FORM 2*PIC(ZZZ,ZZ#)

Outputs:

1,000 0

When the # symbol is used for numeric input with PIC specifications in INPUT FIELDS or RINPUT FIELDS statements, the cursor will automatically skip over non-numeric characters displayed in the field. (The # symbol must be the only digit identifier in the specification.) For example, when slashes are used in inputting a date, the following line 20 will create an output field eight positions long, but the operator will only be able to key into the six numeric positions:

00010 LET D = 112588
00020 RINPUT FIELDS "5,10,PIC(##/##/##),r": D

$

The dollar symbol ($) character operates as both an insertion character and a digit identifier, with the added rule that only one dollar symbol will be printed. The right-most specified dollar symbol, which is not replaced with a digit, will be output as a dollar sign. Any dollar symbols in PIC positions to the left of this one are output as blanks.

In the following example, the first value is output with no spaces between the dollar sign and the value because the PIC specification is designed to use a floating dollar symbol. In contrast, the second PIC specification identifies only one position where the dollar symbol is allowed: all other characters must either be digits or blanks.

00010 PRINT USING 20: 1000,1000
00020 FORM PIC($$$,$$$),X 2,PIC($ZZ,ZZZ)

Output from the above example would look as follows:

$1,000 $ 1,000

*

The asterisk (*) character operates as both a digit identifier and an insertion character, and it is normally used for printing check amounts. Any specified positions, which are not replaced with a digit, will be output as asterisks. Asterisks may be placed either to the left or to the right of the decimal, as in the following example:

00010 PRINT USING 20: 523.50
00020 FORM PIC($********.**)

Output from this example would appear as follows:

$*****523.50

If the amount to be printed in line 10 were 0 rather than 523.50, the output would appear as follows:

$********.**

-

The minus (-) symbol operates as both a digit identifier and an insertion character, with the added rules that the minus sign will be output only when the value to be printed is negative and that only one minus sign (the one closest to the printed value) will be output per value. (Additional minus symbols will be output as blanks.) The minus symbol can be used to indicate either a leading or a trailing sign, as in the following example:

00010 PRINT USING 20: -100,100,-100,100
00020 FORM 2*PIC( - - -),2*PIC(ZZZZZ-)

Output from the above example would look as follows:

-100 100 100- 100

+

The plus (+) symbol operates as both a digit identifier and an insertion character, with the added rules that plus signs will be output only when the value to be printed is positive, and only one plus sign (the one closest to the printed value) will be output per value. (Additional plus symbols in the PIC specification will be output as blanks; a minus sign will be output in the position specified by the plus symbol when the value to be printed is negative.) The plus symbol can be used to indicate either a leading or a trailing sign, as in the following example:

00010 PRINT USING 20: -100,100,-100,100
00020 FORM 2*PIC(++++++),2*PIC(ZZZZZ+)

Output from the above example would appear as follows:

-100 +100 100- 100+

^

The carat (^) symbol is used to input and output data in exponential format. The carat must occupy the three, four or five rightmost positions in the PIC specification. The output positions will be the mantissa value, the letter E, the exponent sign (+ or -) and the exponent value. Values are rounded before printing. The following examples show the output when the number 1.2345E+20 is printed using the following PIC specifications:

Specifications	Output
PIC (# # # # # # # # ^ ^ ^ ^)	1234500E-14
PIC (# #. # # #^ ^ ^ ^ )	12.345E+19
PIC (# # . # # ^ ^ ^ ^ ^)	12.35E+019
PIC (. # # # # # # ^ ^ ^ ^ )	.12345E+21
PIC (ZZZ.# # ^ ^ ^ ^)	123.45E+18
PIC (# # .^ ^ ^ ^ ^)	2. E+019

Parentheses - ( )

PIC((ZZZ,ZZZ.##)) now supports parentheses as digit identifiers (left side of the number only) and insertion characters, with the rule that parentheses will be output only if the number is negative. The left parenthesis that is closest to the number but not replaced with a digit will be output when the number is negative.

00100 PRINT USING "FORM C 4,PIC((((ZZ,ZZZ.##))":"XXXx",-200

output

XXXx   (  200.00)

00100 PRINT USING "FORM C 4,PIC((((ZZ,ZZZ.##))":"XXXx",-200000

output

XXXx (200,000.00)

Insertion Characters

Insertion characters are output exactly where they appear in the PIC specification. The five special insertion characters are: B, D, CR, DR and DB. Any keyboard character other than the digit identifiers listed above is treated as an insertion character. The following example shows two typical uses of insertion characters. The first PIC specification in line 20 prints slashes between the month, day and year of a date. The second prints a colon between the hours and minutes of a time, and it prints the letters "AM" after the time.

00010 PRINT USING 20: 102088,1130
00020 FORM PIC(ZZ/ZZ/ZZ),PIC(BB##:##AM)

The above example outputs:

10/20/88 11:30AM

B Insertion Character

B is a special insertion character: it is always replaced with a blank when formatted. It is used only for System/23 compatibility (a space may be used to accomplish the same result). In the following example, B occupies the second position in the PIC specification.

00010 PRINT USING 20: 100
00020 FORM PIC(ZBZZ)

Output from the above example would look as follows:

1 00

D Insertion Character

D is a special insertion character: it is always replaced with a dash when formatted. This feature is useful for formatting social security numbers and phone numbers, as in the following example

00010 PRINT USING 20: 123456789
00020 FORM PIC(###D##D####)

Output from this example would appear as follows:

123-45-6789

CR, DR and DB

CR, DR and DB are special insertion characters: they print only if the sign of the number is negative.
The following three examples show each of these insertion characters in use:

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZCR)

Output

100CR 100

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZDR)

Output

100DR 100

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZDB)

Output

100DB 100

Conversion errors on G, N, and PIC formats can now be avoided on output to display files when the CONV=parameter is used in the OPEN DISPLAY statement. Also when CONV=is used, PIC processing will first try removing the commas from the output if doing so will prevent an overflow condition.

Other

See the OPEN DISPLAY statement for more information.

See also FMT, a similar method for formatting fields.

When PIC is used with non-numeric data it is processed very similar to the character string specifications C, V and G. Output is not formatted with insertion characters, but during keyboard entry insertion character positions are skipped.

S Format Specification

The S (single-precision floating-point) format specification should be used where speed and/or floating point are required. S can be used with FORM for internal and external files. It is not available with FORM for display files and it cannot be used with full screen processing.

Input characteristics

Since S represents a floating-point number, any number with any amount of decimal positions will be accepted when S is specified. Rounding will not occur. A field length or number of decimal positions is never specified when S is coded. Business Rules four characters of storage for every S-formatted data item.

Output characteristics

All significant digits in S-formatted data will be output exactly as they were input.

Technical Considerations

1.) By definition, S is not portable. It is native to the floating-point format of the machine.

2.) S may be compatible with non-Business Rules files, specifically C files.

3.) D is machine dependent, but all machines should support 10e+-38 with up to 7 digits of precision.

See Also

As a screen attribute, S refers to Sunken Appearance.

V Format Specification

The V format specification identifies string data. It is a highly versatile specification in that it can be used with both types of FORM statements (for internal/external files and for display files), and it can be used with the full screen processing statements.

Input characteristics

For string input, V removes all trailing spaces when reading in a value.

Output characteristics

When V is used for output, leading spaces are retained but blanks are padded on the right, as in the following example:

00010 PRINT USING 20: " ABC","DEF"
00020 FORM C 8,C 3

NOTE that the leading space in " ABC# " is retained:

 ABC  DEF

Technical Considerations

1.) When used for string output, the V, C and G specifications behave identically. On string input, C differs from V and G in that it retains all trailing spaces.

2.) See the VL and VU format specifications for information on variations of V.

VL Format Specification

The VL format specification indicates that string data is to be converted to lowercase upon keyboard input. It can be used with INPUT FIELDS and RINPUT FIELDS processing. (PRINT FIELDS accepts it and treats it the same as V. If it is specified with FORM, error code 1006 will be generated.)

Input characteristics

When VL is used with input of string data, case conversion automatically occurs as the characters are being typed in. Even if the operator attempts to type uppercase letters, only lowercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally -by a VL specification.

The following example will convert all letters entered to lowercase:

00100 INPUT FIELDS "1,40,VL 10,r": X$

Output characteristics

When VL is used for output in PRINT FIELDS or INPUT FIELDS statements, it is treated the same as V. VL cannot be used for either input or output in a FORM statement.

See Also

The letter L can also be used as a Control Attribute.

VU Format Specification

The VU format specification indicates that string data is to be converted to uppercase upon keyboard input. It can be used with INPUT FIELDS and RINPUT FIELDS processing on internal files. (PRINT FIELDS accepts it and treats it the same as V. If it is specified with FORM, error 1006 will be generated.)

Input characteristics

When VU is used with input of string data, case conversion automatically occurs as the characters are being typed in. Even if the operator attempts to type lowercase letters, only uppercase letters will appear on the screen. Characters other than the letters A-Z are not affected. Also, data that is already displayed is not changed -on the screen or internally -by a VU specification.

The following example will convert all letters entered to uppercase:

00100 INPUT FIELDS "1,40,VU 10,r": X$

Output characteristics

When VU is used for output in PRINT FIELDS or RINPUT FIELDS statements, it is treated in the same way as V. VU cannot be used for either input or output in a FORM statement.

ZD Format Specification

The ZD (zoned decimal) format specification is usually used for maximum portability with other computers. It can be used only with FORM statements for internal and external files.

The ZD format specification is now valid for use with display files (PRINT). This was done mainly for S/36 compatibility.

Input characteristics

The decimal point is not stored with a ZD-formatted number. (It is similarly only implied with PD- and B- formatted numbers.) Therefore, the same format specification must be used to retrieve the number as was used to write it. Reading a field with a ZD 5 that was written with a ZD 5.2 results in a number 100 times larger than was written.

Output Characteristics

When ZD is used for numeric output to disk, the number is rounded to the specified number of decimal positions before writing. Each digit is stored in its own byte and has the values 0-9. The last byte also contains the sign, and if the number is negative has the values ), J, K, L, M, N, O, P, Q, R which correspond to -0 through -9, respectively. For example:

00010 WRITE #1,USING 20: 23.1,-23.1
00020 FORM 2*ZD 4.2

Output would be as follows

 2310231

Unformatted File Operations

Applications

READ, REREAD, WRITE, REWRITE

Description

Reading and writing to internal files can be done without using a FORM statement and is called unformatted file I/O. Data records which are written without a FORM statement must contain extra control characters that specify the number of data items in the record and the length of each data item in the record.

Benefits

Unformatted I/O is useful for reading and writing to files that contain control information such as company name, date of last posting, etc. Some additional benefits are as follows:

1. ) The lengths of the fields can be freely changed.
2. ) Fields may be added to the end of the record without affecting the statements that read the record.
3. ) If lengths of variables differ, the variable field length aspect of unformatted I/O often results in a larger number of fields per record than would be possible with formatted I/O.
4. ) Unformatted I/O is faster than formatted I/O.
5. ) Formatted and unformatted records may be mixed in a file, but this is not recommended.

Drawbacks

The control codes used for unformatted I/O increases the record length. Sorts on unformatted files are usually not possible because data fields are not in a fixed position.

Sample usage

The following is an example of unformatted I/O which reads a table of G/L accounts and totals from a control file:

00030 OPEN #1: "NAME=CONTROL", INTERNAL,INPUT,RELATIVE
00040 DIM ACCOUNT$(10), TOTAL(10)
00050 READ #1,REC=5: MAT ACCOUNT$, MAT TOTAL

Using formatted I/O to achieve similar results as above would require a change to line 50 and the addition of line 60, as follows:

00050 READ #1,USING 60,REC=5: MAT ACCOUNT$, MAT TOTAL
00060 FORM 10*C 8,10*L

Record structure

Each time an unformatted record is written or rewritten with unformatted I/O, every item in the record must be output. The WRITE and REWRITE statements start at the beginning of the record and output variables in a specific format.

The first two bytes in an unformatted record are in B (binary) format and contain a count of the number of fields in the record (see the example below). The next byte in the record identifies the length of the field that immediately follows it. The record continues with a pair of fields (the length followed by the data field) for each field in the I/O statement.

When string variables are longer than 255 characters, Business Rules assumes they will be followed by a two-byte field that contains the string length. Numeric variables are output in D floating point format and require eight bytes. When reading numeric variables in an unformatted record, the length of the field must be eight bytes, or a formatting error (0726) will occur.

The following statement generates the sample record format below it:

00040 WRITE #1: "XXX",55,"YY",100,200

Technical considerations

1.) The field length for string variables is determined by the string length being written (the value returned by the LEN function), not the defined length.

2.) All previous variables must be read before a variable in the middle of an unformatted record can be read. The statement READ #1: X$,Y$,Z$, when referring to a record created by the following program line, would cause the system to read "XXX" and 55 before accessing "YY":

00040 WRITE #1: "XXX",55,"YY",100,200

In the above example, Z$ would contain "YY" at the end of the read. Note that the numeric variable can be read into a string field, as can be done with formatted I/O.

2.) B1 fields represent field length in the example above. Field length is limited to 127 characters. Internally, B1 fields are unsigned. B1 fields greater than 127 will show up as negative.