unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 blmode(7)							   blmode(7)




 NAME
      blmode - terminal block mode interface

 DESCRIPTION
      This terminal interface adds functionality to the current termio(7)
      functionality to allow for efficient emulation of MPE terminal driver
      functionality.  Most importantly, it adds the necessary functionality
      to support block mode transfers with HP terminals.  The block mode
      interface only affects input processing and does not affect write
      requests.	 Write requests are always processed as described in
      termio(7).  In character mode the terminal sends each character to the
      system as it is typed.  However, in block mode data is buffered and
      possibly edited locally in the terminal memory as it is typed, then
      sent as a block of data when the Enter key is pressed on the terminal.
      During block mode data transmissions, the incoming data is not echoed
      and no special character processing is performed, other than
      recognizing a data block terminator character.  For subsequent
      character mode transmissions, the existing termio state continues to
      determine echo and character processing.

      There are two parts of the block mode protocol.  The first part is the
      block mode handshake, which works as follows:

	   +  At the beginning of a read, a trigger character is sent to the
	      terminal to notify it that the system is requesting a block of
	      data.  (The trigger character, if defined, is sent at the
	      beginning of all reads, whether character or block.  The
	      trigger character must be defined for block mode reads.)

	   +  After receiving the trigger character, the terminal waits
	      until the user has typed data into the terminal's memory and
	      pressed the terminal Enter key.  The terminal then sends an
	      alert character to the system to notify it that the terminal
	      has a block of data to send.

	   +  The system may then send user-definable cursor positioning or
	      other data sequences to the terminal.  When that is done, the
	      system sends another trigger character to the terminal,
	      repeating the cycle.

      The second part of the block mode protocol is the block mode
      transmission.  During this transmission of data, the incoming data is
      not echoed and no special character processing is performed, other
      than recognizing the data block termination character.  It is possible
      to bypass the block mode handshake and have the block mode
      transmission occur after the first trigger character is sent.

      To prevent data loss, XON/XOFF flow control should be used between the
      system and the terminal.	The IXOFF bit should be set and the terminal
      strapped appropriately.  If flow control is not used, it is possible
      for incoming data to overflow and be lost.  (Note: some older



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 blmode(7)							   blmode(7)




      terminals do not deal correctly with this flow control.)

      It is possible to intermix both character mode and block mode data
      transmissions.  If block mode transmissions are enabled, all transfers
      are handled as block mode transfers.  When block mode transmissions
      are not enabled, character mode transmissions are processed as
      described in termio(7).  If block mode transmissions are not enabled,
      but an alert character is received anywhere in the input data, the
      transmission mode is switched to block mode automatically for a single
      transmission.

      Read requests that receive data from block mode transmissions will not
      be returned until the transmission is complete; i.e., the terminal has
      transmitted all characters.  If the read is satisfied by byte count or
      if a data transmission error occurs, any subsequent data will be
      discarded.  The read waits until completion of the data transmission
      before returning.

      The data block terminator character is included in the data returned
      to the user, and is included in the byte count.  If the number of
      bytes transferred by the terminal in a block mode transfer exceeds the
      number of bytes requested by the user, the read returns the requested
      number of bytes, and the remaining bytes are discarded.  The user can
      determine if data was discarded by checking the last character of the
      returned data.  If the last character is not the terminator character,
      more data was received than was requested, and data was discarded.

      If desired, the application program can provide its own handshake
      mechanism in response to the alert character by selecting the OWNTERM
      mode.  With this mode selected, the driver completes a read request
      when the alert character is received.  The second trigger is sent by
      the driver when the application issues the next read.

      Several special characters (both input and output) are used with block
      mode.  These characters and the normal values used for block mode are
      described below.	The initial value for these characters is 0377,
      which causes them to be disabled.

	   CBTRIG1C	  (DC1) is the initial trigger character sent to the
			  terminal at the beginning of a read request.

	   CBTRIG2C	  (DC1) is the secondary trigger character sent to
			  the terminal after the alert character has been
			  received.

	   CBALERTC	  (DC2) is the alert character sent by the terminal
			  in response to the first trigger character.  It
			  signifies that the terminal is ready to send the
			  data block.  The alert character can be escaped by
			  preceding it with a backslash (\).




 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 blmode(7)							   blmode(7)




	   CBTERMC	  (RS) is sent by the terminal after the block mode
			  transfer is complete.	 It signifies the end of the
			  data block to the computer.

      The two ioctl(2) requests that apply to block mode use the blmodeio
      structure, which defined in <blmodeio.h>, and includes the following
      members:

	      unsigned long   cb_flags;	    /* Modes */
	      unsigned char   cb_trig1c;    /* First trigger */
	      unsigned char   cb_trig2c;    /* Second trigger */
	      unsigned char   cb_alertc;    /* Alert character */
	      unsigned char   cb_termc;	    /* Terminating char */
	      unsigned char   cb_replen;    /* cb_reply length */
	      char	      cb_reply[];   /* optional reply */

      The cb_flags member controls the basic block mode protocol:

	   CB_BMTRANS	0000001	  Enable mandatory block mode transmission.
	   CB_OWNTERM	0000002	  Enable user control of handshake.

	   The CB_BMTRANS bit is only effective when the ICANON flag in
	   termio(7) is set.  If ICANON is clear, all transfers are done in
	   raw mode, regardless of the CB_BMTRANS bit.	If CB_BMTRANS is not
	   set, input processing is performed as described in termio(7).
	   During this time, if the alert character is defined and is
	   detected anywhere in the input stream, the input buffer is
	   flushed and block-mode handshake is invoked.	 The system then
	   sends the cb_trig2c character to the terminal, and a block mode
	   transfer follows.  The alert character can be escaped by
	   preceding it with a backslash (\).

	   If CB_BMTRANS is set, then all transmissions are processed as
	   block mode transmissions.  Block mode handshake is not required
	   and data read is processed as block mode transfer data.  Block
	   mode handshake can still be invoked by receipt of an alert
	   character as the first character received.  Reads issued while
	   the CB_BMTRANS bit is set cause any existing input buffer data to
	   be flushed.

	   If CB_OWNTERM is set, reads are terminated upon receipt of a
	   non-escaped alert character.	 No input buffer flushing is
	   performed and the alert character is returned in the data read.
	   This allows application code to perform its own block-mode
	   handshaking.	 If the bit is clear, an alert character causes
	   normal block mode handshaking to be used.

	   The initial cb_flags value is all-bits-cleared.

      The cb_trig1c character is the initial trigger character sent to the
      terminal at the beginning of a read request.  The initial value is



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 blmode(7)							   blmode(7)




      undefined (0377); i.e., no trigger character is sent.

      The cb_trig2c character is the secondary trigger character sent to the
      terminal after the alert character has been received.  The initial
      value is undefined (0377).

      The cb_alertc character is the alert character sent by the terminal in
      response to the first trigger character sent by the computer.  It
      signifies that the terminal is ready to transmit data.  The initial
      value is undefined (0377).

      The cb_termc character is sent by the terminal after the block mode
      transfer has completed.  It signifies the end of the data block to the
      computer.	 The initial value is undefined (0377).

      The cb_replen member specifies the length in bytes of the cb_reply
      array.  The maximum length of the cb_reply array is NBREPLY bytes.  If
      set to zero, the cb_reply string is not used.  It is initially set to
      zero.

      The cb_reply array contains a string to be sent out after receipt of
      the alert character but before the second trigger character is sent by
      the computer.  Any character can be included in the reply string.	 The
      number of characters sent is specified by cb_replen.  The maximum
      length of the cb_reply array is NBREPLY bytes.  The initial value of
      all characters in the cb_reply array is null.

      On systems that support process group control, ioctl requests are
      restricted from use by background processes, unless otherwise noted
      for a specific request.  An attempt to issue an ioctl request from a
      background process causes the process to block and may cause a SIGTTOU
      signal to be sent to the process group.

      The primary ioctl(2) calls have the form:

	   int ioctl(int fildes, int request, struct blmodeio *arg);

      Requests using this form include:

	   CBGETA	  Get the parameters associated with the block mode
			  interface and store them in the blmodeio structure
			  referenced by arg.  This request is allowed from a
			  background process.  However, the information may
			  be subsequently changed by a foreground process.

	   CBSETA	  Set the parameters associated with the block mode
			  interface from the blmodeio structure referenced
			  by arg.  The change is immediate.

 RETURN VALUE
      Refer to read(2), write(2), and ioctl(2).



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 blmode(7)							   blmode(7)




 ERRORS
      If an error value is returned during a read, it is possible for the
      user's buffer to be altered.  In this case, the data in the user's
      buffer should be ignored because it is incomplete.

      The global variable errno will be set to indicate the following error,
      in addition to those errors described on read(2), write(2), and
      ioctl(2):

      [EIO]	     A read error occurred during the transmission of the
		     block mode data block.

 WARNINGS
      The EIO error that is returned for read errors can be caused by many
      events.  The read returns EIO for transmission, framing, parity,
      break, and overrun errors, or if the internal timer expires.  The
      internal timer starts when the second trigger character is sent by the
      computer, and ends when the terminating character is received by the
      computer.	 The length of this timer is determined by the number of
      bytes requested in the read and the current baud rate, plus an
      additional ten seconds.

 AUTHOR
      The blmode driver was developed by HP.

 SEE ALSO
      termio(7).



























 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000