ddfa(7)

NAME

ddfa − HP DTC Device File Access software

DESCRIPTION

The HP Datacommunications and Terminal Controller (DTC) Device File Access (DDFA) software allows access from HP-UX systems and user-written applications to HP DTC s using standard HP-UX structures. DDFA provides an interface to remote ( LAN -connected) DTC ports that is similar to the interface for local mux ports.

The basic principle is that a daemon is created for each configured port based on information in a configuration file (dp file). When the daemon is spawned, it takes a pty from the pool and creates a device file with the same major and minor number as the pty slave. The device file is known as the “pseudonym”, and user applications use the pseudonym to access the server port using standard HP-UX intrinsics (open(), close(), write(), etc). The daemon listens on the pty until an application does an open(pseudonym), then it manages the connection to the server port. The end result is that the server port is addressed via a device file, but the mechanism that makes it happen is transparent to the user. For example, the lpadmin command can be used to set up a connection to a printer on a remote server port by using the pseudonym. A second configuration file (pcf) contains information to profile the port’s behavior.

DDFA consists of the following items:

dp Dedicated Port configuration file. This text file contains the information DDFA needs to set up and manage a connection to a specified DTC port. It contains a one-line entry for each configured DTC port; the line specifies the board and port, the pseudonym, and the path to the Port Configuration File (pcf).

The dp file is parsed by the Dedicated Port Parser (dpp) which spawns an outgoing connection daemon (ocd) for each connection specified in the file.

dp is also used by the HP-UX telnet daemon (telnetd) to identify incoming connections. In this usage, the daemon negotiates the telnet environment option, and the DTC returns the board and port numbers of the connecting device. telnetd then looks up the port and board numbers in the dp file and maps them to the pseudonym (see dp(4) for more information).

There are two ways to specify a port: explicitly specify its IP address, or specify the IP address of the server, the board, and the port. Alternately, the server’s IP address and the TCP service port address of the port can be given.

pcf Port Configuration File. This file is used by DDFA to configure specific port parameters. pcf is the generic name of the template file. In practice it is renamed for each port, and the values are altered appropriately for the device attached to the port. The pcf is referenced by an entry in the Dedicated Ports file (dp). The Dedicated Port Parser (dpp) parses the dp file and calls the Outbound Connection Daemon (ocd) program to spawn a daemon for each valid line in the dp file. A valid line is one in which the fourth field is the name of a pcf.

dpp Dedicated Port Parser. dpp parses the Dedicated Ports file (dp) and calls the Outbound Connection Daemon (ocd) to spawn a daemon for each valid entry in dp. It can be run from the shell or it can be included in netlinkrc to automatically run the DDFA software each time the system is booted.

dpp has one mandatory argument, the path to the dp file. The other arguments specify an optional log file, the path to ocd if it is not the default, and an option to kill existing processes when the dp file is parsed. dpp can also be run in check mode, where it simply parses the dp file and reports any errors.

ocd Outbound Connection Daemon. ocd manages the connection and data transfer to the remote DTC port. Normally, it is spawned by the Dedicated Port Parser (dpp), but it can be run directly from the shell. If it is run from the shell, the name or IP address of the server or port and the pseudonym (device file name) must be entered on the command line. The board/port number or TCP service port address must be entered if the IP address does not explicitly name a port.

ocd creates a device file for the connection using a file name that is determined by the pseudonym argument. If ocd encounters an error condition that causes it to exit, it normally removes the device file it created.

If a device file is accidentally deleted, the corresponding ocd continues running for at least 30 seconds before it detects the absence of the device file. The ocd then writes an error message to /sys/adm/syslog and exits.

ocdebug Outbound Connection Daemon debug mode. ocdebug is a special version of ocd that contains debug code. ocdebug has to be run from the shell with all the arguments that would normally come from the dp file entered on the command line. Except for -d, the arguments are the same as the ocd arguments. The -d option specifies the level of debugging messages.

INSTALLATION

DDFA is provided in update format, and is installed using the standard HP-UX update command (see update(1M).

Note that update can install software from a tape or a file whose name has the suffix .updt. To install from a file, specify the file name ddfa.updt instead of the device, such as /dev/rct/cldos2. For more information refer to the file readme.ddfa which contains installation instructions.

The files, their default directories, and the correct access permissions are shown below. All files should be owned by user bin, group bin:

-r-xr--r-- /etc/dpp
-r-xr--r-- /etc/ocdebug
-r-xr--r-- /etc/ocd
-rw-r--r-- /etc/newconfig/ddfa/pcf
-rw-r--r-- /etc/newconfig/ddfa/dp
-rw-r--r-- /etc/dpp_login.bin
-rw-r--r-- /etc/utmp.dfa
-rw-r--r-- /etc/readme.ddfa
-r--r--r-- /usr/man/man1m.Z/dpp.1m
-r--r--r-- /usr/man/man1m.Z/ocd.1m
-r--r--r-- /usr/man/man1m.Z/ocdebug.1m
-r--r--r-- /usr/man/man4.Z/dp.4
-r--r--r-- /usr/man/man4.Z/pcf.4
-r--r--r-- /usr/man/man7.Z/ddfa.7

CONFIGURATION

There are two basic steps to configuring DDFA software:

• Entering information in the dp file,

• Entering information in the pcf files.

Configuring the dp file

The dp file contains one line for each connection that is to be established. A template dp file is provided (/etc/newconfig/ddfa/dp) which can be edited directly or a separate file created. It is recommended that the file be copied and the copy edited. We suggest you create the directory /etc/ddfa to contain dp and the pcfs. Note the following points:

• The default file is /etc/newconfig/ddfa/dp; if another file name or path is used, this information must be passed as an argument to dpp (see dpp(1M) for details), whether it is run from the command line or from netlinkrc.

• The exact order of the fields in dp must be maintained:

IP_address board/port pseudonym pc_file_path

• Fields can be separated by spaces or tabs.

• Only one entry is allowed per line.

• Comments can be appended using the # character: everything after the # on any given line is ignored by the parser.

• There are three ways to specify the DTC port: by explicitly giving its IP address, by giving the IP address of the server and then specifying the port and board, or by giving the IP address of the server and the TCP service port address of the port.

• It is recommended that the pcf and device file (pseudonym) are named appropriately so that both can be easily identified (such as when listing processes with ps -ef). For example, the pcf could be named pcf_lp1 and the device file (pseudonym) ocd_lp1, or the pcf could be named pcf_dtc1b2p3 and the device file could be named ocd_dtc1b2p3.

dp file entries contain the following fields:

IP_address This is the IP address of the DTC being accessed, or the IP address of the port on the DTC.

board/port This field contains the DTC board and port numbers, separated by a / character. The board and port numbers are not checked by dpp, but are checked by ocd. Valid values are 0 to 7 for the board, and 0 to 31 for the port (these restrictions do not apply if a TCP service port address is given instead).

If the IP_address field explicitly defines the DTC port, the value in the port/board field must be xx/xx (use X or x).

If the entry is of the form xx/n where n is a decimal number, n is taken to be the TCP port address, and this value is used when the connection is established; otherwise, the destination is filled using the formula (256×(32×board+port+1)+23).

pseudonym This is the absolute path and name of the device file known to the system and/or the end user application. The device file name is limited to 14 characters. We recommend that the name reflects the connected device, and is similar to the pcf name, for example ocd_dtc1b1p1.

pc_file_path This is the path to the Port Configuration File (pcf) that contains the configuration information for the DTC port. This field is mandatory because the parser dpp uses the presence of this field as its flag to spawn a daemon for the line. We recommend that the name of the file reflect the connected device, and be similar to the pcf name, for example pcf_dtc1b1p1.

The following examples illustrate the structure of typical dp file entries.

A printer is connected to port 1 of board 3 of a DTC at IP address 11.234.87.123. The printer attached to the port can be accessed with the HP-UX spooler by specifying device file /dev/ocd_1p1 in the lpadmin command. The port is profiled using data in the file /etc/ddfa/pcf_lp1:

11.234.87.123 03/01 /dev/ocd_lp1 /etc/ddfa/pcf_lp1 # lp1 b1,n2,f7

A printer is connected to the DTC port at IP address 11.234.87.124, so the board/port field contains xx/xx. File pcf_lp2 contains port profiling information.

11.234.87.124 xx/xx /dev/ocd_lp2 /etc/ddfa/pcf_lp2 # lp2 b2,n1

Specify a port using a TCP port address. The port address is calculated using the formula (256×(32×board+port+1)+23).

11.234.87.215 xx/16919 /dev/ocd_lp3 /etc/ddfa/pcf_lp3 # lp3 b2,p1

Configuring the pcfs

Port Configuration Files (pcf) are used to configure individual server ports. /etc/newconfig/ddfa/pcf is a template file; in practice it should be renamed for each port, and the values it contains altered to suit the device attached to the port. We recommend you create the directory /etc/ddfa to contain the modified pcfs and the modified dp file. The pcf is referenced by an entry in the Dedicated Ports file (dp). The Dedicated Port Parser (dpp) parses the dp file and calls the Outbound Connection Daemon (ocd) program to spawn a daemon for each valid line in the dp file; a valid line is one in which the fourth field is the name of a pcf.

Note the following points:

• The order of the variables is not important.

• The file consists of the names of variables and their values. The variables in the template file are shown terminated by a colon (:), but this is not mandatory.

• The variables and their values can be separated by spaces or tabs.

• Only one variable-value pair is allowed per line.

• Only the value should be altered; the variable name must remain the same.

• If you want to use the default values, simply reference the template file /etc/newconfig/ddfa/pcf in the dp file.

• If you want to use different values for a port, make a copy of /etc/newconfig/ddfa/pcf. It is a good idea to name the file appropriately for the pseudonym (device file); for example, pcf_dtc1b2p3.

The file contains the following information:

telnet_mode: Recognized values are disable and enable. When enabled, data transfer over the network uses Telnet protocol. This option must be enabled for the DTC

timing_mark: Recognized values are enable and disable. When enabled, a telnet timing-mark negotiation is sent to the DTC after all user data has been transferred. ocd waits for a reply to the timing mark negotiation before closing the connection. This ensures that all data has been output from the DTC buffers to the device before the buffers are flushed. It should therefore be enabled for the DTC.

telnet_timer: Defines the time, in seconds, during which the software waits for a response to the telnet timing mark and binary negotiation. If the timer expires, an error message is logged to /usr/adm/syslog and the error is transmitted to the user application.

binary_mode: Recognized values are disable and enable. When it is enabled, data transfer over the network is in binary mode, and treatment of special characters (such as XON/XOFF ) is disabled.

Due to the absence of flow control, data integrity cannot be guaranteed when binary_mode is enabled.

Note that even if binary_mode is disabled, it can be negotiated at any time by the application setting IXON to zero in the termio data structure.

open_tries: This defines the number of times the software tries to open a connection before giving up. If the value is 0 the software tries “forever” (approximately 68 years). If the retry process fails, an error message is logged to /usr/adm/syslog. The error message is also transmitted to the user application.

The retry process can be interrupted by sending the SIGUSR2 signal to the ocd process by using kill -17 pid.

Note that if the application exits after asking ocd to open the connection to the DTC, ocd continues trying to open until open_tries and/or open_timer are exceeded.

open_timer: Defines the time, in seconds, between tries. If the value is 0, ocd uses an exponential retry period algorithm up to 32 seconds; that is, 1 2 4 8 16 32 32 32 ...

close_timer: Defines the time, in seconds, between the close call made by the application on the pty slave and the moment when the connection is actually closed. Setting this value to, for example, 5 seconds avoids the overhead of opening and closing the connection when a spooler spools several files at a time. Setting a sufficiently high value effectively leaves the connection permanently open.

status_request: Recognized values are disable and enable. When enabled, the software sends a status request to the printer attached to the server and processes the reply as follows:

LP_OK (0x30) ocd continues processing.

LP_NO_PAPER (0x31) ocd retries within the limits of the status timer.

LP_BUSY (0x32) ocd retries within the limits of the status timer.

LP_OFF_LINE (0x23) ocd retries within the limits of the status timer.

LP_DATA_ERROR (0x38) ocd retries within the limits of the status timer.

status_timer: Defines the time, in seconds, after which the software no longer waits for the reply to the status request. If the timer expires, an error message is logged to /usr/adm/syslog. The error condition is also transmitted to the user application.

eight_bit: Recognized values are enable and disable.

Normally, data bytes processed by the pty have bit 7 stripped. If eight_bit is enabled, the stripping is disabled. If eight_bit is disabled, stripping is enabled, and bit 7 is stripped. This can also be achieved by changing the pseudonym’s termio structure using the ioctl() commands.

tcp_nodelay: Recognized values are enable and disable.

If enabled, data is sent to the LAN as it is received. It can be disabled if the software is sending packets faster than the server can accept.

Default values are:

telnet_mode: enable
timing_mark: enable
telnet_timer: 120
binary_mode: disable
open_tries: 1500
open_timer: 30
close_timer: 0
status_request: disable
status_timer: 30
eight_bit: disable
tcp_nodelay: enable

Configuring netlinkrc

DDFA can be run at boot time by including a reference to dpp in netlinkrc. dpp is run, the dp file is read, and the appropriate processes created. It is recommended that the -k option be used, for example:

dpp:2:once:/etc/dpp /etc/ddfa/dp_file -k

ERROR HANDLING

When ocd receives a serious error condition, such as when the LAN goes down, ocd transmits the error conditions to the application by closing the pty. Any open(), close(), or write() to the pseudonym returns the error condition 0 bytes read . If the pseudonym is the controlling terminal for the group to which the application belongs, sighup is sent to all the processes in the group, including the application.

KILLING DAEMONS

Outbound Connection Daemons (ocds) should be killed using kill -15. kill -9 is not recommended because the device file remains open. ocd verifies the validity of an existing pseudonym before trying to use it. dpp and ocd use data stored in file /etc/utmp.dfa to verify whether a process still owns a pseudonym before taking it over. If ocd finds an unowned pseudonym, it will use it.

ioctl() LIMITATIONS

Not all ioctl functionality is available, due to the lack of a protocol that allows the transmission of such commands over the LAN to the remote port.

TERMIO Attribute Limitations

The main restrictions include modem signal control and parity checking. The following are not available:

IGNPAR INPCK IXOFF
PARMRK IXANY CBAUD

ioctl() Request Limitations

The following ioctl() request limitations apply:

TERMIO structure:

CSTOPB flag DTC only supports one stop bit.

CSIZE DTC only supports 8 bits per character. Value cannot be modified.

PARODD flag DTC offers static configuration to handle even or odd parity. It also handles auto parity detection for even or odd parity.

PARENB flags Enabling/disabling done via static configuration. No programatic interface supplied.

INPCK flag No way to separate input from output parity features.

IGNPAR flag Cannot be configured on DTC.

PARMRK Bad characters are forwarded to the system without marking them with OFFH or OH.

CBAUD Speed is part of static configuration.

IXOFF flag Flow control is enabled if the DTC static configuration specifies an ASCII access mode. If binary is selected, no flow control is provided.

IXON flags Pacing of output to a terminal via a programmatic interface is enabed when ASCII mode is selected in static port configuration and disabled when binary mode is selected.

IXANY flag DTC does not offer ability to restart output on any character received if XOFF was previously received.

HUPCL flag DDFA does not support the hanging up of modem signals on the last close of the device file. If the modem signals used on the DTC drop, the connection is closed.

CLOCAL flag Not supported.

c_flags: IENQACK not supported.

OFILL, OFDEL, NLDLY, CRDLY, TABDLY, BSDLY, FFDLY not supported by TELNETD-DTC software.

BINARY mode flags Part of static configuration is done in DTC Manager by selecting binary mode. If switching is enabled, binary can be selected at user interface level. There is no way to automatically negotiate binary mode when proper termio flags are reset when using telnetd. Binary/ ASCII switching is possible with DDFA. The DTC cannot support large reads in pure binary mode, so transferred blocks of data should not be more than 256 bytes. If half-duplex with remote acknowledgement is implemented, binary applications can be supported.

ioctl() System Call Requests

The following ioctl() system call limitations apply:

TCSBRK The ability to send a break without waiting for previous data to be sent is not provided at system level in telnetd or DDFA. Receiving a telnet break command in the DTC allows it to generate a break on asynchronous ports.

TCFLSH The DTC output queue cannot be flushed.

Hardware handshake request
Not supported on DTC.

TCXONC Local handshake cannot be disabled on DTC.

MCGETA Not supported.

MCSETA, MCSETAF, MCSETAW
There is no way to separately set modem lines of a DTC port.

MCGETT Modem timers, CD timer, connect timer, and disconnect cannot be configured.

CCITT simple, and direct call-in/call-out modes
DTC cannot handle simple mode because there is programmatic interface for modem signals. Call-in mode cannot be simulated if the port is opened, because modem signals (or the call) must be present within 2 minutes or the connection is cleared.

DACIDY get device adapter info
No way to get device adapter information.

download ioctl DACRADDR, DACDLADDR, DACDLGO, DACDLVER
No programmatic call to download the DTC.

DACHWSTATUS, DACSELFTEST, DACLOADED, DACISBROKE status
No programmatic interface to get such info.

DACLOOPBACK DACSUBTEST port test

FILES

/etc/dpp
/etc/ocdebug
/etc/ocd
/etc/dpp_login.bin
/etc/utmp.dfa
/etc/newconfig/ddfa/pcf
/etc/newconfig/ddfa/dp

Museum

Related Articles