Kednos PL/I for OpenVMS Systems
Reference Manual
Previous Contents Index

9.2.6.2 Simple Output to a Terminal

You can send data to a terminal with the PUT LIST statement. A simple form of PUT LIST is as: 

PUT LIST (output-source,...);

The output sources in simple cases are expressions, including variable references. The PUT LIST statement converts the results of the expressions to the appropriate character representations and sends the character strings to the terminal. For instance: 


PUT LIST (A,B,C);
This statement converts the values of the variables A, B, and C to character strings and sends the results to the terminal. In this simple case, the displayed strings are separated by tabs.

The file SYSPRINT, used as the default output stream by PUT LIST, is a print file, and the terminal has the characteristics of print files. For example, on RISC ULTRIX, the ENDPAGE condition is signaled when the terminal's page size is exceeded.

9.2.6.3 Print File

A print file is a stream output file that is intended for output on a terminal, line printer, or other output device. You can declare any stream output file to be a print file by using the PRINT attribute. The default stream output file, SYSPRINT, is a print file.

The following list describes the special features of print files, as opposed to ordinary stream output files:

Examples 


SIMPLE_INPUT: PROCEDURE OPTIONS (MAIN); 
      /* Simple input from user's terminal */ 
DECLARE 
      BADGE_NUMBER FIXED DECIMAL (5), 
      SOCIAL_SECURITY_NUMBER CHARACTER(11); 
 
GET LIST (BADGE_NUMBER,SOCIAL_SECURITY_NUMBER); 
 
PUT LIST (BADGE_NUMBER,SOCIAL_SECURITY_NUMBER); 
 
END SIMPLE_INPUT;

PL/I does not display a prompt character on the terminal when a program executes a GET or READ statement. Consequently, it is difficult to tell that a program is trying to read data unless the program executes an output statement containing a prompting message. The program SIMPLE_INPUT would be easier to use if the following statement appeared immediately before GET LIST: 


PUT SKIP 
LIST('Enter badge number, social security number:');

The cursor remains on the same line after the prompt is displayed, so the input can be entered on the same line. The completed line might be as: 


Enter badge number, social security number: 7,116-40-0482[Return]

The GET statement also has a PROMPT statement option that displays a prompt on the user's terminal. See the Kednos PL/I for OpenVMS Systems User Manual. 


TIN: PROCEDURE OPTIONS(MAIN); 
 
DECLARE STRING CHAR(10) VARYING, 
      I FIXED BINARY STATIC INITIAL(0), 
      A FLOAT BINARY; 
DECLARE EOF BIT STATIC INITIAL('0'B); 
 
ON ENDFILE(SYSIN) EOF = '1'B; 
 
PUT SKIP LIST('Enter string, integer, float>'); 
GET LIST(STRING,I,A); 
DO WHILE(^EOF); /* stop when CTRL/Z is typed */ 
 
      PUT SKIP LIST(STRING,I,A); 
      PUT SKIP LIST('Enter string, integer, float>'); 
      GET LIST(STRING,I,A); 
END; 
 
END TIN;

Here, the user is prompted to enter three values from the default file SYSIN. The three values are immediately written out to the default file SYSPRINT. This sequence continues until the user answers the prompt with a Ctrl/Z, which signals the ENDFILE condition for SYSIN; the program then terminates. The following is a sample dialog with the program: 


$ RUN TIN[Return]
 
Enter string, integer, float> JONES,27,3.75[Return]
JONES               27   3.7500000E+00 
Enter string, integer, float> JONES 27 3.75[Return]
JONES               27   3.7500000E+00 
Enter string, integer, float> JONES[Return]
27[Return]3.75[Return]
JONES               27   3.7500000E+00 
Enter string, integer, float> DOOLEY[Return][Return]4E-6[Return]
DOOLEY               0   4.0000000E-06 
Enter string, integer, float> [Ctrl/Z]
$

Notice that input fields are separated by commas, spaces, or the RETURN key. Notice also that entering a blank line after <BIT_STRING>(DOOLEY) causes the program to set the value of I to zero.

Other Topics

The following topics are of interest in terminal I/O applications:

9.3 Record I/O

Record I/O is performed by the READ, WRITE, DELETE, and REWRITE statements. In record I/O, each I/O statement processes an entire record. (In stream I/O, more than one line or record can be processed by a single statement.) Table 9-4 summarizes the file description attributes that apply to record I/O.

Table 9-4 Attributes and Access Modes for OpenVMS Record Files

Attributes
Specified
Attributes
Implied 		Valid Devices
and File
Organizations 		Usage
SEQUENTIAL
OUTPUT 		RECORD Any output
device or file
except indexed 		Records can be added to the end of the file with WRITE statements. Each WRITE statement adds a single record to the file.
SEQUENTIAL
INPUT 		RECORD Any input
device or file 		Records in the file are read with READ statements. Each statement reads a single record.
SEQUENTIAL
UPDATE 		RECORD Relative,
indexed,
stream 		READ statements read a file's records in order. PL/I maintains the current record, which is the record just read. This record can be replaced in a REWRITE statement. In a relative or indexed sequential file, the current record can also be deleted with a DELETE statement. Each statement processes a single record.
DIRECT
OUTPUT 1 		KEYED
RECORD 		Relative,
stream 		WRITE statements insert records into the file at positions specified by keys. Each statement inserts a single record.
DIRECT
INPUT 		KEYED
RECORD 		Relative,
indexed,
stream 		READ statements specify records to be read randomly by key. Each statement reads a single record.
DIRECT
UPDATE 		KEYED
RECORD 		Relative,
indexed,
stream 		READ, WRITE, and REWRITE statements specify records randomly by key. In a relative or indexed file, records can also be deleted by key.
KEYED
SEQUENTIAL
OUTPUT 1 		RECORD Relative,
stream 		WRITE statements insert records into the file at positions specified by keys. Each statement inserts a single record. This mode is identical to DIRECT OUTPUT.
KEYED
SEQUENTIAL
INPUT 		RECORD Relative,
indexed,
stream 		READ statements access records in the file randomly by key or sequentially.
KEYED
SEQUENTIAL
UPDATE 		RECORD Relative,
indexed,
stream 		Any record I/O operation is allowed except a WRITE statement that does not specify a key or a DELETE statement for a sequential disk file with fixed-length records.

1You cannot create indexed sequential files directly from a PL/I OPEN statement.

9.3.1 READ Statement

The READ statement reads a record from a file, either the next record or a record specified by the KEY option. The file must have either the INPUT or the UPDATE attribute.

The format of the READ statement is:

FILE(file-reference)

The file from which the record is to be read. If the file is not currently open, PL/I opens the file with the implied attributes RECORD and INPUT. The implied attributes are merged with the attributes specified in the file's declaration.

INTO (variable-reference)

An option that specifies that the contents of the record are to be assigned to the specified variable. The variable must be an addressable variable. The INTO and SET options are mutually exclusive.

SET (pointer-variable)

An option that specifies that the record should be read into a buffer allocated by PL/I and that the specified pointer variable should be assigned the value of the location of the buffer in storage. The SET and INTO options are mutually exclusive.

This buffer remains allocated until the next operation on the file but no longer. Therefore, do not use either the pointer value or the buffer after the next operation on the file. The only valid use of the buffer during a subsequent I/O operation is in a REWRITE statement. In this case, you can rewrite the record from the buffer before the buffer is deallocated.

KEY (expression)

An option that specifies that the record to be read is to be located using the key specified by the expression. The file must have the KEYED attribute. The key value must have a computational data type. The KEY and KEYTO options are mutually exclusive.

The nature of the key depends on the file's organization, as follows:

KEYTO (variable-reference)

An option that specifies that the key of the record being read is to be assigned to the designated variable. The value of the key is converted from the data type implied by the file's organization to the data type of the variable. The variable must have a computational data type but cannot be an unaligned bit string or an aggregate consisting entirely of unaligned bit strings. The KEYTO and KEY options are mutually exclusive.

KEYTO is specified only for a file that has both the KEYED and SEQUENTIAL attributes.

OPTIONS (option,...)

An option that specifies one or more of the following READ statement options, separated by commas:
FIXED_CONTROL_TO (variable-reference)  
INDEX_NUMBER (expression)  
LOCK_ON_READ  
LOCK_ON_WRITE  
MANUAL_UNLOCKING  
MATCH_GREATER  
MATCH_GREATER_EQUAL  
MATCH_NEXT  
MATCH_NEXT_EQUAL  
NOLOCK  
NONEXISTENT_RECORD  
READ_REGARDLESS  
RECORD_ID (variable-reference)  
RECORD_ID_TO (variable-reference)  
TIMEOUT_PERIOD (variable-reference)  
WAIT_FOR_RECORD  

All these options except INDEX_NUMBER remain in effect for the current statement only.

These options are described fully in the Kednos PL/I for OpenVMS Systems User Manual.

9.3.1.1 File Positioning Following a READ Statement

If the file is accessed sequentially, the READ statement reads the file's next record. If the next-record position is at the end-of-file, the ENDFILE condition is signaled.

After a successful read operation, the file's current record position denotes the record that was just read. The next-record position denotes the following record or, if there is no following record, the end-of-file.

If any error other than an incorrect record size occurs, the current record becomes undefined and the next record is the same as it was before the read operation was attempted.

Examples 


COPY: PROCEDURE; 
DECLARE INREC CHARACTER(80) VARYING, 
        ENDED BIT(1) STATIC INIT('0'B), 
        (INFILE,OUTFILE) FILE; 
 
      OPEN FILE (INFILE) RECORD INPUT 
               TITLE('RECFILE.DAT'); 
      OPEN FILE (OUTFILE) RECORD OUTPUT 
               TITLE('COPYFILE.DAT'); 
      ON ENDFILE(INFILE) ENDED = '1'B; 
 
      READ FILE(INFILE) INTO (INREC); 
      DO WHILE (^ENDED); 
               WRITE FILE (OUTFILE) FROM (INREC); 
               READ FILE (INFILE) INTO (INREC); 
               END; 
      CLOSE FILE(INFILE); 
      CLOSE FILE(OUTFILE); 
      RETURN; 
      END;

The program COPY reads a file with variable-length records into a character string with the VARYING attribute and writes the records to a new output file.

It uses a DO-group to read the records in the file sequentially until the end-of-file is reached. It uses the ON statement to establish the action to be taken when the end-of-file occurs: it sets the bit ENDED to <BIT_STRING>(1)B so that the DO-group will not be executed again.

The VARYING character-string variable INREC has a maximum length of 80 characters. If any record in the file is more than 80 characters, the ERROR condition is signaled. If no ERROR ON-unit exists, the program exits. 


DECLARE 1 STATE, 
          2 NAME CHARACTER(30), 
          2 CAPITAL, 
            3 NAME CHARACTER(20), 
               .
               .
               .
          2 SYMBOLS, 
            3 FLOWER CHARACTER(30), 
            3 BIRD CHARACTER(30), 
      STATE_FILE FILE, 
 
      INPUT_NAME CHARACTER(30) VARYING; 
         .
         .
         .
OPEN FILE(STATE_FILE) KEYED ENVIRONMENT(INDEXED); 
    PUT SKIP LIST('State?'); 
    GET LIST(INPUT_NAME); 
    READ FILE(STATE_FILE) INTO(STATE) KEY(INPUT_NAME); 
    PUT SKIP LIST('The flower of',STATE.NAME,'is the', 
         STATE.SYMBOLS,STATE.SYMBOLS.FLOWER);

This example shows the use of a keyed READ statement to access a record in an indexed sequential file. The file STATE_FILE is opened for keyed access, and the READ statement specifies the key of interest in the KEY option. The value for this option is determined at run time by a GET statement. In the READ statement, the contents of a record from the file STATE_FILE are read into the structure STATE. 


PRINT_DATA: PROCEDURE OPTIONS(MAIN); 
 
DECLARE 1 EMPLOYEE BASED (EP), 
          2 NAME, 
            3 LAST CHAR(30), 
            3 FIRST CHAR(20), 
            3 MIDDLE_INIT CHAR(1), 
          2 DEPARTMENT CHAR(4), 
          2 SALARY FIXED DECIMAL (6,2), 
    EP POINTER, 
    EMP_FILE FILE; 
 
DECLARE EOF BIT(1) STATIC INIT('0'B), 
      NUMBER FIXED BIN(31); 
 
      ON ENDFILE(EMP_FILE) EOF = '1'B; 
      OPEN FILE(EMP_FILE) INPUT SEQUENTIAL KEYED; 
 
      READ FILE(EMP_FILE) SET(EP) KEYTO(NUMBER); 
      DO WHILE (^EOF); 
         PUT SKIP LIST('EMPLOYEE',NUMBER, 
              EMPLOYEE.NAME.FIRST,EMPLOYEE.NAME.LAST, 
              EMPLOYEE.NAME.MIDDLE_INIT); 
         READ FILE(EMP_FILE) SET(EP) KEYTO(NUMBER); 
         END; 
      CLOSE FILE(EMP_FILE); 
 
END;

This program accesses a relative file sequentially with READ statements and obtains the key value of each record, that is, the relative record number. The records in the file EMP_FILE are arranged according to employee numbers. Each employee number corresponds to a relative record number in the file. The READ statements read records into the based structure EMPLOYEE and set the pointer EP to the location of the allocated buffer. The READ statements specify the KEYTO option to obtain the record number of each record. The procedure prints the employee numbers and names. When the last record has been read, the program closes the input file and exits.

9.3.2 WRITE Statement

The WRITE statement adds a record to a file, either at the end of a file that has the SEQUENTIAL and OUTPUT attributes, or in a specified key position in a file that has the KEYED and OUTPUT attributes or the KEYED and UPDATE attributes. The format of the WRITE statement is:

FILE (file-reference)

A reference to the file to which the record is to be written. If the file is not currently open, the WRITE statement opens the file with the implied attributes RECORD, OUTPUT, and SEQUENTIAL; these attributes are merged with the attributes specified in the file's declaration.

FROM (variable-reference)

A reference to the variable containing data for the output record. The variable must be addressable.

If the variable has the VARYING or the AREA attribute and the file does not have the attribute ENVIRONMENT(SCALARVARYING), the WRITE statement writes only the current value of the varying string or the area into the specified record. In all other cases, the WRITE statement writes the entire storage of the variable. If the contents of the variable do not fit the specified record size, the WRITE statement outputs as much of the variable as will fit, and the ERROR condition is signaled.

KEYFROM (expression)

An option specifying that the record to be written is to be positioned in the file according to the key specified by the expression. The file must have the KEYED attribute.

The nature of the key depends on the file's organization, as follows:

OPTIONS (option,...)

An option specifying one or more of the following WRITE statement options, separated by commas:
FIXED_CONTROL_FROM (variable-reference)  
RECORD_ID_TO (variable-reference)  

These options are described fully in the Kednos PL/I for OpenVMS Systems User Manual.

Previous Next Contents Index