FCONTROL

Quick jump: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54

Itemnum/ Mnemonic Item Description

0/U16

General device control

The value specified is passed to the appropriate device driver. A value from the driver is returned in item. Not valid for spooled device files.

1/U16

Carriage control (CCTL)

Passes a carriage control directive to the driver of the specified nonspooled device file, regardless of whether the file is opened CCTL or NOCCTL. For spooled devices, use FWRITE to pass carriage control directives. (Refer to the FWRITE intrinsic for these directives.)

If item passes either the prespacing (%101 or %401) or postspacing (%100 or %400) carriage control directives, one of the following values is returned in item, indicating the setting of the device prior to the FCONTROL call

0	Postspacing
1	Prespacing

If both a mode control directive and a carriage control directive need to be specified, an additional call to FWRITE or FCONTROL must be made.

This itemnum is ignored for byte stream files. It is not applicable to directories since applications are not permitted to write to directory files.

Default: postspacing with automatic page eject (except for FORTRAN77/XL and COBOLII/XL: prespacing with automatic page eject).

2/I16

Complete I/O

Ensures that requested I/O has been physically completed. Valid only for buffered files. Posts the block being written (full or not). Ignored for message files.

Item is ignored.

This itemnum is supported for byte stream files. It is not applicable to directories since applications are not permitted to write to directory files.

(KSAM) A checkpoint record is written. In the event of a system crash, recovery would be done to this state of the files.

3/U16

Device status

Returns a record containing information about the state of the device associated with the file immediately after the last I/O operation (including HPFOPEN/FOPEN) on the file. The record size and contents are device-dependent.

4/U16

Set read timeout interval

Passes the timeout interval, in seconds, to be applied to the next read from the specified file. The maximum value allowed is 65,535 seconds. If input is requested from a file but is not received in this interval, the FREAD request terminates with CCL (1). The interval is specified in seconds and returned no value. If this interval is zero, any previously established interval is cancelled, and no timeout occurs.

If a timeout value is being set for a read posted against a device connected through a PAD, add enough time to compensate for time delays that may be caused by the network.

A timeout value should be used for programs reading from an unattended device to prevent "hangs". Timeouts can be used to terminate binary reads (only as a safeguard to prevent a program from waiting forever for a read to complete).

Only valid for terminal and message files. Only affects the next read if the file is being read from the terminal; it must be reissued for each read. If this code is applied to a message file, item specifies the length of time that a process waits when reading from an empty file or writing to a full one and the timeout remains enabled until it is explicitly cancelled.

During block mode reads, the timer halts when a DC2 character is received. At this time, the block mode read timer is activated by the system; its values are not user changeable.

5/U16

Reposition file at its beginning

The next record, read or written, is the first record in the file. Not valid for files accessed as append-only. On a labeled magnetic tape file or serial disk file, the tape is positioned at the beginning of the opened file, and not necessarily at the beginning of the volume. Rejected for spooled DATA tapes.

Item is ignored.

This itemnum is supported for byte stream files and all types of directories.

(KSAM) The file is repositioned to the first logical record; the record with the lowest value in the current key.

6/U16

Write end-of-file

Marks the end-of-file (EOF) on disk or magnetic tape and is effective only for those devices:

If used for a disk file it writes a logical end-of-data marker where the file was last accessed. The disk file label is updated and written to disk.
If used for a file residing on unlabeled magnetic tape, a tape mark is written at that current position.
If used for message files, it verifies the state of the file by writing the file label and buffer area to disk; ensures the message file can survive system crashes. No EOF is written.
If used for KSAM files, it performs the function of itemnum=2 and writes the file label. This guarantees that the end-of-file is correct and the extent bit map is updated.

Rejected for spooled DATA tapes and labeled magnetic tape files.

Item is ignored.

This itemnum is supported for byte stream files. It is not applicable to directories since applications are not permitted to write to directory files.

7/U16

Space forward to tape mark

Moves a magnetic tape forward until a tape mark is encountered. If used on labeled magnetic tapes, the tape is positioned at the beginning of user trailer labels, if any. Rejected for spooled DATA tapes.

Item is ignored.

(KSAM) Not used for KSAM XL files. For KSAM/3000 files, it clears the key and data buffers of all information and reads the first 2 sectors of the key file from disk to buffer.

8/U16

Space backward to tape mark

On unlabeled tapes, moves a magnetic tape backward until a tape mark is encountered. If used on labeled tapes, the tape is positioned at the beginning of user header labels, if any. Rejected for spooled DATA tapes.

Item is ignored.

(KSAM) Not used for KSAM files.

9/U16

Rewind and unload tape

Repositions a magnetic tape file at its beginning and places the tape offline. Not allowed for labeled tapes. Rejected for spooled DATA tapes and labeled magnetic tape files.

Item is ignored.

10/U16

Change line speed of a device

Passes a value specifying a new line speed for both input and output.

The value passed must be expressed in characters per second (1 character per second = 10-bits per second). The supported choices are

30	(300 bps)
120	(1200 bps)
240	(2400 bps)
960	(9600 bps)
1920	(19200 bps)

Any setting other than those listed returns CCL (1).

The speed associated with the device must match the physical speed settings of the device/modem. If the speed setting is changed programmatically, a request that the speed setting of the device be manually changed should be made.

If issued against a terminal connected through PAD, CCE (2) is returned, but there is no effect on the transmission speed, and a meaningless value is returned in item.

When a device is initially opened programmatically, the speed is set to the default device speed. If the device is opened as a logon device (configured with speed and parity sensing enabled), the speed setting is sensed from the first carriage return character received. The default device speed is configured through the Node Management Configuration Manager (NMMGR) or the OpenView DTC Manager (networks managed by an OpenView workstation). Reconfigure the device to permanently change the speed.

Not reset in break mode; not reset after FCLOSE.

Item is ignored.

11/U16

Change line speed of a device

Passes a value specifying a new line speed for both input and output.

The value passed must be expressed in characters per second (1 character per second = 10-bits per second). The supported choices are:

30	(300 bps)
120	(1200 bps)
240	(2400 bps)
960	(9600 bps)
1920	(19200 bps)

Any setting other than those listed returns CCL (1).

If issued against a terminal connected through PAD, CCE (2) is returned, but there is no effect on the transmission speed, and a meaningless value is returned in item.

Not reset in break mode; not reset after FCLOSE.

Item is ignored.

12/U16

Enable echo facility

Returns a value indicating the previous echo status:

0	Echo ON
1	Echo OFF

When enabled, all characters transmitted to the DTC are echoed onto the terminal's screen (DTC echo). When the system is initialized, all characters are echoed except for XON, XOFF, NULL, DEL, and DC2. During binary reads, all characters are passed as data and echoed. For this reason, echo should be disabled while in binary mode.

During block mode processing, echo should be disabled and local echo should be used to cause the terminal to write data back to the screen. If VPLUS is being used for block mode applications, this is done automatically. For all other types of block mode, disable echo before the block mode read begins.

Echo should be disabled if a terminal user is entering data that should not appear on the screen (for example, passwords or lockwords).

Echo should be disabled when connecting some nonsupported devices to an asynchronous port.

Reset in break mode; not reset after FCLOSE. (Default)

13/U16

Enable echo facility

Returns a value indicating the previous echo status:

0	Echo ON
1	Echo OFF

Echo should be disabled if a terminal user is entering data that should not appear on the screen (for example, passwords or lockwords).

Echo should be disabled when connecting some nonsupported devices to an asynchronous port.

Reset in break mode; not reset after FCLOSE. (Default)

14/U16

Disable system break function

Enter a value of 1 to disable the system break function.

System break is enabled by default for any terminal on which a session is active. If a user presses BREAK or a process calls the CAUSEBREAK intrinsic, the system attempts to interrupt the processing and place the terminal at the command interpreter level. Many system commands and program commands (that invoke subsystems or run user programs) are breakable.

When the system break is enabled and received, EOR, read timer, terminal mode, and echo values are saved by the DTS software. This allows restoration when normal processing is resumed. If a system break is entered during processing of a character mode read or write, data is lost. Any read that is interrupted by a break is reissued by the system after a RESUME command is entered.

Some application programs change the settings of terminals and/or the characteristics of their device files. In these cases, it may be undesirable to allow system break processing to occur. For example, disable system break when using block mode. This prevents data loss or corruption that could occur if BREAK is pressed during a block mode read.

Reset after FCLOSE. If BREAK is pressed while system break is disabled, no action is taken by any level of software. System break has no effect on a device with no active session.

15/U16

Enable system break function

Item has no meaning; enter a value of 0 to satisfy internal requirements.

System break is enabled by default for any terminal on which a session is active. If a user presses BREAK or the CAUSEBREAK intrinsic is called, the system attempts to interrupt the processing and place the terminal at the command interpreter level. Many system commands and program commands (that invoke subsystems or run user programs) are breakable.

Reset after FCLOSE. (Default) If BREAK is pressed while system break is disabled, no action is taken by any level of software. System break has no effect on a device with no active session.

16/U16

Disable subsystem break function

Item has no meaning; enter a value of 0 to satisfy internal requirements.

Subsystem break is initially disabled on all devices; it must be enabled before it can be used. It is available only for devices running sessions and has no effect on programmatically controlled devices. Subsystem break is reset to disabled at FCLOSE.

When enabled, the user can stop a program-local or subsystem-local command. It is invoked by the subsystem break character. (The default subsystem break character is CTRL-Y.)

When enabled for a terminal connected through PAD, the subsystem break must be followed by RETURN to signal the PAD that data is ready.

Before enabling the subsystem break, call the XCONTRAP intrinsic to arm the subsystem break trap procedure. When a subsystem break is entered, the subsystem break trap is disarmed. The RESETCONTROL intrinsic must be called to allow another subsystem break to occur.

Subsystem break processing is summarized as follows:

A user-written procedure must be provided defining how the subsystem break trap handler will react upon receipt of a subsystem break. The user program must contain:
- The user written procedure.
- A call to XCONTRAP, specifying the external label of the procedure; this arms the subsystem break trap.
- A call to FCONTROL Itemnum=17, enabling the subsystem break function.
- A call to RESETCONTROL when the program is ready to receive another subsystem break.
A new subsystem break character can be defined through FCONTROL Itemnum=41 if the terminal is placed in transparent mode or through FDEVICECONTROL, which allows a subsystem break character to be defined without placing the device in the transparent mode.
At any time, FCONTROL can be called to disable the subsystem break.

Reset in break mode; reset after FCLOSE. (Default)

17/U16

Enable subsystem break function

Item has no meaning; enter a value of 0 to satisfy internal requirements.

Subsystem break is initially disabled on all devices; it must be enabled before it can be used. It is available only for devices running sessions, and has no effect on programmatically controlled devices. Subsystem break is reset to disabled at FCLOSE.

When enabled, the user can stop a program-local or subsystem-local command. It is invoked by the subsystem break character. (The default subsystem break character is CTRL-Y.)

When enabled for a terminal connected through PAD, the subsystem break must be followed by RETURN to signal the PAD that data is ready.

Subsystem break processing is summarized as follows:

A user-written procedure must be provided defining how the subsystem break trap handler will react upon receipt of a subsystem break. The user program must contain:
- The user written procedure.
- A call to XCONTRAP, specifying the external label of the procedure; this arms the subsystem break trap.
- A call to FCONTROL itemnum=17, enabling the subsystem break function.
- A call to RESETCONTROL when the program is ready to receive another subsystem break.
A new subsystem break character can be defined through FCONTROL itemnum=41 if the terminal is placed in transparent mode or through FDEVICECONTROL, which allows a subsystem break character to be defined without placing the device in the transparent mode.
At any time, FCONTROL can be called to disable the subsystem break.

Reset in break mode; reset after FCLOSE. (Default)

18/U16

Disable tape option

(Default)

Item is ignored.

19/U16

Enable tape option

Item is ignored.

20/U16

Disable the terminal input timer

Reset in break mode; reset after FCLOSE. (Default)

Item is ignored.

21/U16

Enable the terminal input timer

Reset in break mode; reset after FCLOSE.

Item is ignored.

22/U16

Read the terminal input timer

Item returns the measured time duration of the last read.

The result of the read duration timer is returned in hundredths of a second, up to 655.35 seconds.

The operating system times each and every read, therefore, this call should immediately follow the read of interest with no subsequent reads between.

23/U16

Disable parity checking and generation

Item has no meaning; enter a value of 0 to satisfy internal requirements.

If a call is issued against a terminal connected through PAD, CCE (2) is returned, but the device control action does not take place.

Parity can be used for terminals opened programmatically and for those in session mode. The default for these is to operate in 8-bit pass-through mode (no parity).

If a terminal detects a parity error, it displays the PAD character.

If a parity error is detected by ASC software, the current read is completed in error, and no read data is returned. The ASC software reports the error to the program reading the data.

24/U16

Enable parity checking and generation

Item has no meaning; enter a value of 0 to satisfy internal requirements.

If a call is issued against a terminal connected through PAD, CCE (2) is returned, but the device control action does not take place.

Parity can be used for terminals opened programmatically and for those in session mode. The default for these is to operate in 8-bit pass-through mode.

If a terminal detects a parity error, it displays the PAD character.

If a parity error is detected by ASC software, the current read is completed in error, and no read data is returned. The ASC software reports the error to the program reading the data.

When enabled, the ASC software generates parity on outgoing data and checks the parity errors on incoming data. After the parity is checked, the parity bit is always set to zero. (The program using the data does not need parity data.) Parity checking is handled the same in block mode and in character mode.

When enabling parity, ensure that the program also requests the terminal operator to change the physical parity setting of the terminal to the new setting of the ASC software. Also, if the terminal is to check parity on incoming data, the local terminal control (used to turn parity checking on or off) should be set to ON.

25/U16

Define additional end-of-record characters

Item passes the value of a character to be used as an additional end-of-record (AEOR) character. The octal or decimal code for the character must be in the right byte of the parameter; the left byte is ignored. If the NULL character (%0) is specified, default EOR conditions are restored.

Normally, character mode reads using standard editing are terminated by a RETURN. The system echoes the carriage return and sends a linefeed to the terminal, the cursor is positioned at the beginning of the next line, ready for the next read. If an AEOR is assigned, an EOR character still terminates a read as usual.

When a read is terminated by an AEOR, the AEOR character is included in both the data and byte counts. No carriage return or line feed is sent to the terminal. The read terminates with an error condition indicating that the AEOR character was encountered.

The AEOR character is also recognized in transparent editing mode, along with a user-defined EOR character. (This replaces the normal EOR character.)

To disable the AEOR character, indicate item=0.

The following are not recognized as AEOR characters:

ASCII Characters	Octal Code	Hex Code	Terminal Keys

NUL (null)	%0	$0	CTRL-@
DC1 (XON)	%21	$11	CTRL-Q
DC3 (XOFF)	%23	$13	CTRL-S
DEL (Rubout)	%31	$19	DEL
Subsystem Break	%177	$7F	CTRL-Y (default)

Note: Avoid using characters that have a special meaning specifically, carriage return, linefeed, cancel, backspace, DC2, or escape. These characters will be recognized and processed, but they can result in unpredictable and unsuccessful results.

Do not use CTRL-A as an AEOR character at the console.

26/U16

Disable binary mode

Item has no meaning, enter a value of 0 to satisfy internal requirements.

Ignored for terminals connected through PAD.

Binary mode is disabled by default.

27/U16

Enable binary mode

Item has no meaning, enter a value of 0 to satisfy internal requirements.

If this call is issued to a device connected through PAD, it is ignored; however, the next FREAD posted to the device returns an error.

When binary mode is enabled, no special characters are processed; all characters are considered data and are passed through without any terminal control actions being taken. After a binary read, no carriage return or line feed is sent to the terminal. All carriage control directives are ignored on writes. Unless echo is disabled, any ASCII DC3 (XOFF) character passed in data is echoed to the terminal, and the terminal is suspended. Block mode transfers cannot be made.

Binary mode does not take effect until a read is posted to the device following the FCONTROL call. If binary mode is enabled for both reads and writes, post a 0 byte read immediately after the call to ensure binary mode is enabled.

Binary mode is useful for transferring 8-bit data to and from a terminal. Because all 8-bits are considered to be data, binary mode is not compatible with parity checking; parity must be disabled.

In session mode, a system break restores standard editing at the terminal. If RESUME is entered following the system break, binary mode is restored when the first read is posted.

Binary reads are terminated on byte count, as specified in the FREAD, READ, or READX call. Errors and read timeouts also terminate binary reads, but an error code is returned and no data is transferred.

28/U16

Disable user block mode

Item has no meaning; enter a value of 0 to satisfy internal requirements.

Ignored for terminals connected through PAD.

User block mode is not supported with terminal type 18.

Under system default conditions, block mode processing occurs through a method called Hewlett-Packard block mode. The system controls the block mode handshake if block mode transfers are being made and the program does not need to worry about the data transfer protocol. The host transmits a DC1 character to inform the terminal that the system is ready to receive data. The terminal responds with a DC2 character to inform the system that the next data transfer is a block mode transmission. The terminal then waits for the host to send a second DC1 character to initiate the read.

When transmitting data in block mode, the terminal must be configured to be compatible with the system and the application requesting the block mode transfer.

Note: Data overruns can occur during block mode transfers. The program must check for successful completion of each read, and retry as required. Use of timers during block mode is encouraged to eliminate port "hangs" due to a data overrun occurring when the last character is read. The standard block mode read timer is disabled when the user block mode protocol is enabled.

Not reset in break mode; not reset after FCLOSE. (Default)

29/U16

Enable user block mode

Item has no meaning; enter a value of 0 to satisfy internal requirements.

Ignored for terminals connected through PAD.

User block mode is not supported with terminal type 18.

When user block mode is enabled and block mode transfers are being made, the program can intervene in the block mode handshake. A user block mode transaction begins with the DC1 character and then the program takes control of the handshake until the DC2 character is encountered. The program can perform additional terminal control functions, such as positioning the terminal cursor, performing status requests, or collating additional space for buffers before continuing with the data transfer. When the program is ready to receive block mode data, an additional read must be issued (DC1 character) to complete the handshake.

When transmitting data in block mode, the terminal must be configured to be compatible with the system and the application requesting the block mode transfer.

Not reset in break mode; not reset after FCLOSE. Under default conditions, user block mode is disabled.

30/ Reserved

31/ Reserved

32/ Reserved

33/ Reserved

34/U16

Enable line deletion response

Item has no meaning; enter a value of 0 to satisfy internal requirements.

In character mode, with standard editing, the computer will output !!!, carriage return, and line feed when the line deletion (cancel) character is entered. This is referred to as CTRL-X echo (the default line deletion character).

Not reset in break mode; reset after FCLOSE. (Default)

For devices connected through PAD the line deletion response is never printed in response to the line deletion character. If this call is issued, condition code CCE (2) is returned, but no device control action occurs.

35/U16

Disable line deletion response

Item has no meaning; enter a value of 0 to satisfy internal requirements.

The line deletion response can be suppressed by calling this parameter. The data is deleted in the input buffer, but no !!!, carriage return, line feed is issued.

Not reset in break mode; reset after FCLOSE (enables line deletion suppression, the system default condition).

For devices connected through PAD, the line deletion response is never printed in response to the line deletion character. If this call is issued, condition code CCE (2) is returned, but no device control action occurs.

36/U16

Set parity

Item passes a value representing the specified parity condition and then returns the value of a previous setting:

0	No parity check on input, eighth bit set to 0 on output (parity type = zeros)
1	No parity check on input, eighth bit set to 1 on output (parity type = ones)
2	Even parity checked on input, even parity generated on output (parity type = even)
3	Odd parity checked on input, odd parity generated on output (parity type = odd)

When specified, this option changes the terminal parity setting, and the previous setting is returned to the call as the new value of item. It is possible to determine a terminal's parity setting with parity disabled.

Parity cannot be used with 8-bit character sets.

Ignored for devices connected through PAD.

37/U16

Set terminal type and speed

Item passes a value specifying line speed and terminal type. Bits (0:11) specify the line speed; bits (11:5) specify the terminal type.

Ensure that the speed associated with a device matches the physical speed setting of the device and modem (if part of the connection). If the device speed is being changed programmatically, request that the speed setting be manually changed on the device.

If an attempt is made to set an unsupported speed or terminal type, condition code CCL (1) is returned.

Do not use this call to specify a user-defined terminal type.

If used for devices connected through PAD, the call changes the terminal type setting, but does not change how the device actually operates. Condition code CCE (2) is returned.

38/U16

Set terminal type

Item passes the value of the system-defined terminal type to be associated with an asynchronous port.

Changes the terminal type associated with a port to another system-defined terminal type. The new terminal type remains in effect until another FCONTROL call is made or the device is closed. If the device is closed, the port resets to its configured terminal type.

The terminal type specified must be a currently supported system-defined terminal type. If another value is used, condition code CCL (1) is returned.

This call cannot be used to change to a user-defined terminal type.

If used for a terminal connected through PAD, there is no effect on the terminal control settings of the device. Condition code CCE (2) is returned.

39/U16

Obtain terminal type information

Item returns the terminal type associated with the asynchronous port. Use this information to get the original setting before calling itemnum=37 or 38.

Note: Do not confuse the current terminal type returned with the default terminal type specified during system configuration. Changing the terminal type during logon or through system intrinsics can cause a difference from the configured setting. To reset the configured terminal type, use itemnum=37 and item=0 or close the device.

40/U16

Obtain terminal output speed

Item returns the current line speed associated with an asynchronous port in characters per second. Use this information to get the original setting before calling itemnum=11 or 37.

Note: Do not confuse the current line speed returned with the default line speed specified during system configuration. Changing the line speed through system intrinsics can cause a difference from the configured setting. To reset the configured line speed, use itemnum=37 and item=0 or close the device.

If used for a terminal connected through PAD, the value returned in item is meaningless. Condition code CCE (2) is returned.

41/U16

Enable transparent editing

Item passes a value to be used as a subsystem break character in bits (0:8) and a value to be used as a read terminator in bits (8:8). Returns the values previously assigned for use as subsystem break and read terminator characters.

When enabled, allows most special characters to be read and treated as data and a small subset to retain their meaning:

AEOR: The AEOR character defined through a previous call to itemnum=25. The read terminates in error, and a call to FCHECK returns an error code of 31. The AEOR character is passed with the data and included in the byte count.
BREAK: Causes a system break (when enabled) and transfers control to the operating system. If the RESUME command is entered, transparent editing is resumed.
CTRL-Q (DC1 or XON): The resume output character of the XON/XOFF handshake. This character is stripped from the input data when XON/XOFF protocol is enabled.
CTRL-R (DC2): When input as the first character, it is stripped out. A DC1 (CTRL-Q) is written to the terminal. If not input as the first character, DC2 is a data character.
CTRL-S (DC3 or XOFF): The stop output character of the XON/XOFF handshake. This character is stripped from the input data when XON/XOFF protocol is enabled.
item bits (0:8): Specifies the character that replaces the subsystem break character. Any character not defined as a special character in transparent mode (including the standard subsystem break character) can be used. If set to 0, subsystem break is disabled.
item bits (8:8): Specifies the character that replaces the line termination character (EOR). Any character not defined as a special character in transparent mode can be used.

Item=0 disables transparent editing mode and returns to standard editing mode.

Transparent mode reads can be terminated in any of the following ways:

The read encountered the EOR character defined in item. This character functions like a RETURN character in normal reads and is stripped when found. No carriage return or line feed is sent to the terminal.
The read encountered an AEOR character, defined through a previous call to FCONTROL itemnum=25. The read completes with an error condition and the AEOR character is passed with the input data and and included in the byte count. No carriage return or line feed is sent to the terminal.
The expected byte count is reached. The read is terminated normally, and carriage return and line feed are sent to the terminal.
The read limit timer expired. All data is lost and the read terminates in error.

Break or subsystem break processing, if not disabled, occurs in transparent editing. During a break, the terminal operates in standard editing mode. The terminal returns to transparent editing mode if the RESUME command is entered. During a subsystem break, the terminal operates the way the application program describes.

Parity processing is the same in transparent editing as it is in standard editing.

Any FCLOSE call issued against the terminal restores standard editing.

If used for a device connected through PAD, data is not forwarded from the terminal immediately after the characters defined as the subsystem break or EOR character are typed. The terminal user has to press RETURN to cause data to be transmitted, or wait for the data forwarding timer to expire (if set). The host software recognizes and acts on the characters defined in item.

42/ Reserved

43/U16

Aborts pending nowait I/O request

For message files, CCG (0) is returned when an outstanding I/O operation has completed. An IOWAIT call must be issued to finish the request.

44/U16 Reserved

45/U16

Enable/disable extended wait

Applicable only if filenum specifies a message file. An item value of 1 enables extended wait; permits a reader to wait on an empty file that is not currently opened by any writer, or a writer to wait on a full file that has no reader. This remains in effect until an FCONTROL call is issued with an itemnum 45 and an item value of 0. An item value of 0 specifies that if a second FREAD call is issued and it encounters an empty file that has no reader, it returns an end-of-file condition. Each assessor must call FCONTROL45 individually.

Default: 0

46/U16

Enable/disable reading writer's ID

Applicable only if filenum specifies a message file.

For interprocess communication, an item value of 1 enables reading the writer's ID. Each record read has a two-word header. The first word indicates the type of record:

0	Data record
1	Open record
2	Close record

The second word contains the writer's ID number. If the record is a data record, the data follows the header. Open and close records contain no more information. If the item value is 0, reading the writer's ID is disabled. Only data is read to the reader's target area. The open and close records are skipped and deleted by the file system when they come to the head of the message queue, and the two-word header is transparent to the reader.

Default: 0

47/U16

Nondestructive read

Applicable only if filenum specifies a message file.

If the item value is 1, the next FREAD by this reader does not delete the record. Subsequent FREAD calls are unaffected. When item is specified as 0, the next FREAD deletes the record.

Default: 0

48/U16

Arm/disarm software interrupts

Passes a value that arms/disarms the software interrupt mechanism (valid only if filenum specifies a message file). To arm the file's software interrupt, pass the external procedure label (NM plabel) or the interrupt procedure. To disarm the software interrupt, pass a value of zero.

49/ Reserved

50/ Reserved

51/U16

Append mode

Enables or disables append mode based on the value of the item parameter. Append mode is enabled if item is one (1) and disabled if item is zero (0). Write operations append data at the end of a file while reads and seeks may occur anywhere within the file when POSIX append mode is enabled for that file.

Append mode differs from opening a file for append access in several ways:

1	Append `mode` can be enabled and disabled while a file is open. Append `access` is established when opening a file and cannot be changed dynamically for a file number.
2	Append `access` is a process-local attribute affecting only the access of the process which opened the file. Append `mode` affects all processes sharing a logical record pointer. (The MULTI and GMULTI options permits logical record pointers to be shared.)
3	A file's logical record pointer can be manipulated through `FPOINT` or `FREADDIR` when append `mode` is active. Append `access` prohibits logical record pointer operations. For example, call to `FPOINT` and `FSPACE` result in an access violation for files opened for append `access`.

This itemnum is supported only for byte stream files. If the file referenced by filenum is not a byte stream file. FCONTROL will fail with a CCL condition code. An error code of 42 (operation inconsistent with device type) is returned by FCHECK when it is called following this FCONTROL error.

52/U16

Set Nonblock

This option can be used to set and reset the Nonblock flag of a file. When the Nonblock flag is true, any attempt to perform I/O to the file, results in the I/O procedure returning without blocking. If the I/O can be performed without blocking, then the I/O is completed normally. When Nonblock is false, I/O's will block if necessary. The item parameter must be set to 1 in order to cause the Nonblock flag to be set to true. A value of zero will reset the Nonblock flag. Any other value fo the item parameter results in an error being returned.

The default value of item is 0.

Not all file types support this option.

53/U16

Close File on Exec

This option allows the caller to set or reset closure of a specified file when a POSIX exec( ) function is called. An item value of 0 causes the file remain open on an exec( ). A value of 1 causes the file to close when an exec( ) is performed. All other values of the item parameter return an FSERR 8 - ILLEGAL PARAMETER VALUE error. The default value of item is 0.

54/*

pointer to ioctl parameter structure

This item provides for compatibility with the ioct() function found in most UNIX implementations. This option is only valid for streams and network socket files and tape devices. Any attempt to use this option with other file types results in an FSERR 8 - ILLEGAL PARAMETER VALUE error.

The item parameter must point to a structure that contains three ioctl() parameters:

Request
Arg
ioctl functional return

The first 32 bits contain a short pointer to the arg parameter. The arg parameter is pointed to by reference due to the variable length depending upon the requested function. The last 32 bits of the structure contains the address of the location to write the functional return. Due to the nature of the functional return, this item is an output only address. In pascal, the structure is defined as follows:


  ioctl_parm_ptr = ^ioctl_parm_type;

  ioctl_parm_type = record
    request      : integer;
    arg          : localanyptr;
    func_return  : localanyptr;
  end;

The caller must correctly fill in the values of the structure before calling the FCONTROL intrinsic. The functions that are supported through this option are defined as standard documentation on the ioctl() function.

FCONTROL

MPE documents

Syntax

Parameters

FCONTROL Itemnum/Item Values

Operation Notes

Condition Codes

Related Information