Writing to Asynchronous Devices

Using FWRITE

FWRITE transfers a record of data to a file on any device. You must first open a file on the device with write access specified and obtain a valid file number. The file number is then used by the FWRITE call to access the file. The syntax of FWRITE is as follows:

        I16V	    UDS   I16V	      U16V

FWRITE(filenum,buffer,length,controlcode);

The filenum parameter passes the file number of the file to which data will be written. The record to be written is passed in the buffer parameter, with the length of the data specified in the length parameter. A positive or negative value is used to indicate whether length is halfwords or bytes. You should be aware, however, that for asynchronous devices, physical data transfer will always occur on a byte-by-byte basis. Specifying halfwords will result in an even number of bytes being output.

If length is 0, no data transfer will occur. You might use FWRITE with length specified as 0 to set line spacing (carriage control) at the device before any data is output.

Carriage control is passed through the controlcode parameter. The carriage control specification can be 0, 1, or one of the values designated as controlcode values for MPE/iX. Table 8-11 “Selected Carriage Control Directives” lists many of the carriage control directive values most commonly used with asynchronous devices. For a complete list of carriage control directive codes that can be used with the FWRITE intrinsic you should see the MPE/iX Intrinsics Reference Manual.

If controlcode is 0, the full record of data will be transferred to the devicefile, up to a maximum of 132 characters per printed line, and single spacing will be applied.

If controlcode is 1, the first character of the data will be interpreted as space control and will be suppressed when the data is printed. Any of the values supported as carriage control directives can be used as the first character when this method is used.

The carriage control directive values can also be applied directly through the controlcode parameter. Simply use one of these values instead of a 0 or 1.

When writing to a terminal, a controlcode value of %320 is often used. This value specifies that no carriage control will be sent to the terminal and the next character printed by the next write will physically follow the data written by the current write. You might use a controlcode of %320 when prompting for user input at a terminal. No carriage return or linefeed will follow the write and the cursor will be positioned next to the prompt.

Figure 3-5 “Illustration of the FWRITE Intrinsic” illustrates the use of the FWRITE intrinsic. This code fragment opens a terminal file as $STDLIST with write access specified. The prompt to be written to the terminal is placed into buffer and the variable cctl is specified as %320. FWRITE is then called using these values. The result will be that the prompt "Enter Your Name" will be written to the device and the cursor will be placed next to the prompt.

Your program should check condition codes after each FWRITE; however, you should be aware that this intrinsic is completed logically. This means that once data is passed to an output buffer the write is considered to have completed successfully. If the output device has suspended operation, due to flow control or some other reason, the actual write may not have occurred. There is no programmatic way to verify the physical output of data to a device.

Figure 3-5 Illustration of the FWRITE Intrinsic

FWRITE(file_num, esc_seq, -5, octal('320'));

Using PRINT

In much the same way that READ and READX provide a quick method for reading from the standard input device, PRINT provides a quick method for writing to the standard output device. PRINT sends a string of ASCII characters to $STDLIST. The syntax of the call is as follows:

       CA	I     16V		     I16V

PRINT(message,length,controlcode);

The message parameter is a character array that holds the string to be written to the device. It must begin on a halfword boundary, as must all character arrays.

The length parameter specifies the length of the character string. If the length of the message exceeds the configured record length of the terminal, successive records will be written.

The controlcode parameter specifies the carriage control to be applied when the message is output. Either a 0, 1, or one of the valid carriage control directives should be passed in this parameter. See the discussion of the FWRITE intrinsic for more information on controlcode values.

Like READ and READX, PRINT has a number of limitations on the way it can be used. Because no file number is available, :FILE commands are not useful, nor is it possible to use the FCHECK intrinsic to check error conditions. For permanent programs it is recommended that FWRITE be used instead.