Examples

Setting Transparent Editing Mode

In Figure 4-1 “FDEVICECONTROL to Enable Transparent Mode” transparent editing mode is enabled at a terminal through the FDEVICECONTROL intrinsic. Transparent editing mode is also referred to as unedited mode. The parameters of the call specify how the control action is to take place.

A file number, obtained through a previous call to FOPEN or HPFOPEN issued against the device to be controlled, is contained in the port parameter. (The file open call is not shown in the example.) The controlcode is set to 192, indicating that this is a device control operation.

The parm1 value is set to 15, which is the control directive used to set transparent editing mode. The parm2 value is 2, specifying that only Write access is needed. This means that a value will be passed in the buffer parameter, but the previous value will not be returned.

When you use FCONTROL to enable transparent editing, you specify new subsystem break and EOR characters through one of the parameters of the call. You must also specify these characters when you enable transparent mode through FDEVICECONTROL. You pass the value corresponding to the characters you want to use through the buffer parameter. Any character not otherwise defined as a special character in transparent mode can be used.

The example shown here uses the Pascal/iX ord function to set the subsystem break and EOR characters through a variable called value. The high order bit of value contains a slash (/), which will be the new subsystem break character, and the low order bit contains an asterisk (*), which will be the new end-of-record character. This variable value is passed through the buffer parameter.

One other notable feature of the example is the way errors are handled. The example uses the fserrorcode parameter to provide information to the user in the event of an error by writing the file system error number to the standard output device.

Figure 4-1 FDEVICECONTROL to Enable Transparent Mode

You also call FDEVICECONTROL with a control directive of 15 to disable transparent editing mode. To return to standard editing, call FDEVICECONTROL with parm1 set to 15, but specify 0 for both the subsystem break and EOR characters. Figure 4-2 “FDEVICECONTROL to Disable Transparent Mode” provides an example of disabling transparent mode. Note that, in this example, parm2 specifies both Read and Write access for the call. The subsystem break and EOR characters in effect before the call executed can therefore be identified and reported after the intrinsic completes successfully.

Figure 4-2 FDEVICECONTROL to Disable Transparent Mode

Specifying an End-of-Record Character

You can change the character that will be recognized as the end-of-record character for a device by specifying a control directive of 39 and passing the desired character in buffer. This FDEVICECONTROL is effective in either standard and transparent editing mode. Note that the call does not alter the editing mode in effect for the device; it simply changes the character that will signal the end of a record for that device. This capability is not available through any FCONTROL function.

You might want to use this capability, for example, to make it possible for carriage returns to be passed in your data without enabling binary editing mode and without modifying the processing of any other special character. Only the end-of-record character is affected by this control directive.

A notable characteristic of this use of FDEVICECONTROL is that the value of the new end-of-record character must be passed in the high order byte of the buffer parameter. The low order byte is not used with this control directive. (Two other FDEVICECONTROL control directives, 40 and 41, also require that the value be passed in the high order byte.)

In Figure 4-3 “FDEVICECONTROL to Specify EOR Character”, FDEVICECONTROL is used to change the end-of-record character to a bracket (]). Again, the value of the character is specified through the Pascal/iX ord function and is then multiplied by 256 to place it in the high order byte. Read/Write access is set to Write only for the call, so the previous EOR character will not be returned to the program.

To return to normal end-of-record processing, call this FDEVICECONTROL again, specifying a null value as the EOR character. The EOR character will be reset to the default character, which is the carriage return. If you were processing in transparent mode prior to changing the EOR character, and want to return to using the EOR character that you specified in the call that established transparent mode, you need to explicitly reset the EOR to that character.

Figure 4-3 FDEVICECONTROL to Specify EOR Character

Controlling Backspace Processing

Among the capabilities provided by FDEVICECONTROL which are not available through other intrinsics is the ability to manipulate how backspace processing takes place at a device. You can specify the character that the DTC will recognize as a backspace when it is sent from a specific device. You can also, to a limited extent, control the action that the DTC will take as a result of the backspace character being entered at a specific device. These controls are independent of each other, enabling you to change either the backspace character, the backspace response, or both, depending on the needs of your application. They are only useful in standard editing mode, since backspace is not recognized as a special character in either transparent or binary editing modes.

You use FDEVICECONTROL with a control directive of 36 to change the character that the DTC will recognize and act on as a backspace character. In the program fragment shown in Figure 4-4 “Specifying a New Backspace Character”, the backspace character in effect for the devicefile whose file number is contained in port is set to a dollar sign ($), using the Pascal/iX ord function to specify its value. The program then notifies the user that the backspace character has been changed. Read/Write access is set to 2, which means that the backspace character previously in effect will not be returned.

If a dollar sign is entered at the device after successful execution of the program, it will be treated as a backspace, and the DTC will perform backspace processing. The dollar sign will not be echoed to the terminal, nor will it be passed in the data stream as a character of data.

In addition, the special processing characteristics normally associated with the backspace character itself ([CTRL]H) will be disabled, and, if a backspace is entered from the device, it will be passed in the data stream.

Figure 4-4 Specifying a New Backspace Character

The code fragment shown in Figure 4-5 “Setting Backspace Response” illustrates another aspect of backspace processing that can be manipulated through the FDEVICECONTROL intrinsic. In this example, a control directive of 55 is used to select a backspace response action. The backspace response action is the action that will be taken by the DTC as a result of a backspace (or the designated backspace character) being entered from a terminal.

There are two valid backspace response actions for MPE/iX systems. The default response is for the DTC to discard the character that was to the left of the terminal's cursor when the backspace was entered and to move the cursor back one space. The discarded character remains on the terminal screen until the user types a new character.

The second valid backspace response action is for the discarded character to be erased from the screen. To accomplish this, the DTC backspaces the terminal cursor as usual, but then transmits a space to erase the character from the screen and a second backspace to place the cursor at the correct position for the next character to be entered.

Either of these backspace response actions can be set through FDEVICECONTROL using a control directive of 55. To specify that the character on the screen should be erased, set the value of buffer to 5. To return to normal backspace response, set the value of buffer to 1.

The example shown in Figure 4-5 “Setting Backspace Response” sets the backspace response to erase by specifying a 5 as the value of buffer.

Figure 4-5 Setting Backspace Response

Controlling Device XON/XOFF Processing

Another device control feature provided by the FDEVICECONTROL intrinsic is the ability to disable (and subsequently reenable) XON/XOFF flow control between a device and the DTC.

XON/XOFF protocol provides the main method of flow control used by MPE/iX systems. The protocol controls the flow of data transmitted between the DTC and a device to protect against data overruns.

XON/XOFF flow control allows the device receiving a transmission to stop the flow of data coming in should the device become temporarily unable to receive the data. It does this by sending an XOFF character to the DTC. XOFF is the ASCII DC3 character ([CTRL]S).

When the device is once again able to receive data, it transmits an XON character to signal that the DTC should resume data transmission. XON is the ASCII DC1 character ([CTRL]Q).

When XON/XOFF flow control is enabled, the DC1 and DC3 characters are not transmitted to the host. XON/XOFF flow control is enabled by default. All devices supported for use on MPE/iX systems are capable of using XON/XOFF protocol.

The only time XON/XOFF flow control is normally not active is during binary mode reads. This is because the DC1 and DC3 characters are not recognized as special characters in binary editing mode. However, no other special character processing occurs in this mode, either.

By using FDEVICECONTROL with a control directive of 26, it is possible to disable XON/XOFF flow control without altering any other aspect of how the device operates. It then becomes possible to transmit DC1 and DC3 characters to the host without causing the DTC to suspend transmission. All other special characters will still be recognized, and the associated special character functions will be performed. You should only use this capability when it is absolutely necessary to do so, however, and always with extreme care. When XON/XOFF flow control is disabled, it is possible for data overruns to occur and for data to be lost as a result.

The program fragment shown in Figure 4-6 “Disable Device XON/XOFF Processing” provides an example of using FDEVICECONTROL to disable device XON/XOFF flow control. The parm1 value of 26 specifies that the call is to set device XON/XOFF. The value variable contained in the buffer parameter is set to 0, which indicates that XON/XOFF is to be disabled by the call.

To re-enable device XON/XOFF you would call FDEVICECONTROL with a control directive of 26 again, but this time you would set the value of buffer to 1.

Figure 4-6 Disable Device XON/XOFF Processing

Controlling Host and Device XON/XOFF Processing

Another host and device control feature provided by the FDEVICECONTROL intrinsic is the ability to disable (and subsequently reenable) XON/XOFF flow control between device and the DTC. See Figure 4-7 “Enable Host XON/XOFF Processing” for enabling host XON/XOFF processing.

XON/XOFF protocol provides the main method of flow control used by MPE/iX systems. The protocol controls the flow of data transmitted between DTC and the device to protect against data overruns.

Device XON/XOFF flow control allows the device receiving a transmission to stop the flow of data coming in should the device become temporarily unable to receive the data. It does this by sending an XOFF character to the DTC. XOFF is the ASCII DC3 character ([CTRL]S).

Host XON/XOFF flow control allows the DTC receiving a transmission to stop the flow of data coming in should the DTC become temporarily unable to receive the data. It does this by sending an XOFF character to the device. XOFF is the ASCII DC3 character.

When the device is once again able to receive data, it transmits an XON character to signal that the DTC should resume data transmission. XON is the ASCII DC1 character ([CTRL]Q)

When the DTC is once again able to receive data, it transmits an XON character to signal that the device should resume data transmission. XON is the ASCII DC1 character ([CNTRL]Q).

By using FDEVICECONTROL with a control directive of 76, it is possible to disable XON/XOFF flow control between device and the DTC.

The functionality for device flow control (FDEVICECONTROL 192,26) is maintained for backward compatibility, even though that can be done through this FDEVICECONTROL.

Figure 4-7 Enable Host XON/XOFF Processing

Setting the Number of Stop Bits

Among the capabilities provided by FDEVICECONTROL is to specify or set the number of stop bits used. By using FDEVICECONTROL with a control directive of 71, it is possible to set the number of stop bits used. There are two possible buffer values to specify the number of stop bits used. See Figure 4-8 “Set the Number of Stop Bits” on how to set the number of stop bits equal to two.

In asynchronous communication, the stop bit informs the receiving device where the character ends. Thus it helps the receiving and sending machines to synchronize the transmission.

Figure 4-8 Set the Number of Stop Bits

Enabling Escape Sequence Read Termination

FDEVICECONTROL has the ability to control the interpretation of escape sequences. Escape sequences are usually generated by function keys or cursor control keys. The escape sequence read termination (parm1 = 68) control directive allows your application to react immediately to a special key when it reads it.

The escape sequence read termination causes a read to terminate when the escape character is encountered in input data. However, the read does not terminate immediately.

The DTC starts a timer immediately after it receives the escape character. The DTC sets the timer to the period of time required to transmit two characters at the current line speed. Characters that are automatically transmitted as part of the escape sequence will be received. When the entire escape sequence is transmitted, the timer will expire, the read terminates, and your application can respond to the special meaning of the escape sequence.

	NOTE: The escape sequence may contain any number of characters, but the time between the reception of each character in the sequence cannot exceed the timer.

Enable/Disable escape sequence read termination (parm1 = 68) should be accompanied with the enable/disable suppress echo of read termination characters function (parm1 = 69). This prevents the DTC from echoing the escape sequence characters and guarantees that your application always has control of the position of the cursor. For example, you could design a function key to display a help message and then return to the point on the input line where the function key was typed. See Figure 4-9 “Escape Sequence Read Termination” for escape sequence read termination.

Figure 4-9 Escape Sequence Read Termination