Updated: 11 December 1998

OpenVMS I/O User's Reference Manual

An application port is used to connect to a remote device (typically a printer) on a terminal server or to a dedicated port on another LAT service node. The LAT port driver can only connect to a remote device if the device is currently not in use. Table 5-30 lists the conditions that can occur when an application program issues an IO$M_LT_CONNECT request for a connection to a remote device. After a request is queued on the terminal server (or dedicated port on another LAT service node), the QIO request is not completed until the connection is established, rejected, or times out.

Table 5-30 IO$M_LT_CONNECT Request Status

Event	IOSB Status	Explanation
Connection established	SS$_NORMAL	The connection is successful, and the port is ready for use.
Connection timeout	SS$_TIMEOUT	The connection did not complete because communication was never established with the remote end. IOSB+2 contains LAT$_CONTIMEOUT.
Connection rejected	SS$_ABORT. IOSB+2 contains LAT rejection code or LAT facility message code.	The connection cannot be made. The LAT port driver updates the I/O status block. The LAT rejection codes (0--19) are listed in Table 5-32.
Connection request	SS$_ILLIOFUNC	The QIO request is not to an application, dedicated, or forward port. The LAT port driver rejects the request immediately.
Connection already established on port	SS$_DEVACTIVE	The QIO request is for a port already in use. The LAT port driver rejects the request immediately.
Incorrectly configured LAT port	SS$_DEVREQERR	The LAT port is incorrectly configured. This may mean that the port type was neither forward nor application nor dedicated, because a forward port had no service name mapped or because an application port had no node name mapped.
Insufficient resources	SS$_INSFMEM	The QIO request failed because the LAT port driver could not get system memory to complete the connection.

Before the application port can be used, it must be mapped to a remote node name, and either the port name or the service name of the remote terminal server port. (These names must be defined locally on the terminal server.) The application port is mapped with the IO$M_LT_SETMODE modifier, specifying the following items in the P1 itemlist parameter:

• LAT$_ITM_TARGET_NODE_NAME---The node name. The node name is the name of the terminal server where the application device is located.
• LAT$_ITM_TARGET_PORT_NAME---The port name.
• LAT$_ITM_TARGET_SERVICE_NAME---The service name.

The queued status of the connection can also be mapped to the port by specifying the LAT$_ITM_QUEUED item in the P1 itemlist parameter. Valid values for this item are:

• LAT$C_ENABLED---Port has queued status. This is the default.
• LAT$C_DISABLED---The port does not have queued status.

Rather than the normal timesharing service offered by the operating system, application programs can make use of LAT application services that allow terminal server users (or users on sytems with outgoing connections) to connect to a specialized application. To do this, the system manager must create LAT ports that are dedicated to a particular application service. (Alternatively, this LAT port creation can be done from a program using the QIOs discussed in previous sections, providing OPER privilege.) When the remote user makes the connection to the application service, the connection is directly to the application program that controls a LAT port (LTA device) associated with the service. In this case the prompt, Username:, is not received. Compaq recommends that you follow these steps to create an application service:

1. Define the dedicated ports in LAT$SYSTARTUP.COM and execute the command procedure in SYSTARTUP_VMS.COM. (Refer to the OpenVMS System Management Utilities Reference Manual and the OpenVMS System Manager's Manual for additional information.)
2. Run the application program. Within the application program, allocate dedicated ports with the same name as those defined in LAT$SYSTARTUP.COM. Use the Assign I/O Channel ($ASSIGN) system service to assign service channels to the ports.
3. Post a read request to the dedicated ports. When the terminal user connects to the service and presses the Return key, the application program can perform I/O to the dedicated port.
4. To break the connection, use the Deassign I/O Channel ($DASSGN) system service to deassign the channel and the Deallocate Device ($DALLOC) system service to deallocate the device. The application program must reallocate the port and reassign the channel in preparation for the next connection.

An example of the application service concept is a program that provides the time of day. For this example, the system manager includes the following lines in LAT$SYSTARTUP.COM (or enters them manually in the LATCP program):

CREATE SERVICE TIME/ID="At the tone, the time will be"/APPLICATION CREATE PORT LTA99:/DEDICATED SET PORT LTA99:/SERVICE=TIME

An application program then assigns a channel to device LTA99. When a terminal server user types CONNECT TIME, the user is connected to this application program, and the program prints out the time of day. The program then deassigns the channel, which disconnects the server user.

A system manager may associate more than one LAT port with the same service. In that case, the application program that offers the service should assign channels to all of the LTA devices created for that service.

5.4.4.7 Programming Forward Ports

An outbound LAT connection to a remote service node can be made using a forward port. The LAT port driver can connect to a remote service node only if outgoing connections are enabled on the local node. Outgoing connections can be enabled with LATCP or with a LAT SETMODE QIO to the local node. In addition, user group codes on the local node must match the service group codes of the service to which they are being connected. LATCP can list the services to which the local node can connect. (See the OpenVMS System Management Utilities Reference Manual for additional information.) Before the forward port can be used to make an outbound LAT connection, it must be mapped to a service and optionally, a node and port. The forward port is mapped with the IO$M_LT_SETMODE modifier, specifying the following items in the P1 item list parameter:

• LAT$_ITM_TARGET_SERVICE_NAME---The service name. The service name is the name of the service to which to connect.
• LAT$_ITM_TARGET_NODE_NAME---The node name. The node name is the name of a specific service node offering the service.
• LAT$_ITM_TARGET_PORT_NAME---The port name. The port name is the name of a specific port on the target node. The LAT$_ITM_TARGET_NODE_NAME item must be supplied when supplying this item.
• LAT$_ITM_SERVICE_PASSWORD---The password. The password is required for access to a password-protected service.

A LAT SETMODE QIO on a forward port does not require OPER privilege if the port name is not specified in the P4 parameter. In other words, the LAT SETMODE QIO must be to the port corresponding to the CHAN parameter (the forward port attained by assigning a channel to _LTA0:). Note that SS$_NOPRIV is returned if you attempt to change the port type by specifying the LAT$_ITM_PORT_TYPE item code in the P1 itemlist parameter. If the P4 parameter is specified, the LAT port driver also returns SS$_NOPRIV.

Table 5-30 lists the conditions that can occur when an application program issues an IO$M_LT_CONNECT request for a connection to a remote service node. The QIO request is completed when a session is established with the service node. Once the connection completes, data can be read and written to the port with the QIO read and write functions.

5.4.4.8 Queue Change Notification (Alpha Only)

On Alpha systems, the IO$M_LT_QUE_CHG_NOTIF function modifier for $QIO allows a process to enable an attention asynchronous system trap (AST), which is used with the LAT $QIO connect request. The IO$M_LT_QUE_CHG_NOTIF function is available only for APPLICATION and FORWARD LAT devices.

If a $QIO connect request has been issued to a remote node and that request has been queued, this attention AST will be set each time the queue position changes. This AST can be used as long as the $QIO connect request is queued. Like a Ctrl/Y AST, it is set only once; it must be reenabled after each completion.

If the LAT $QIO connect succeeds or if a LAT connection exists for the intended service, the AST completes with the SS$_DEVACTIVE status code.

If the LAT device does not have the queued characteristic, issuing the IO$M_LT_QUE_CHG_NOTIF function results in the return of SS$_DEVREQERR status code.

The implementation of IO$M_LT_QUE_CHG_NOTIF is shown in the following C example:

status - sys$qiow ( 0, /* efn */ ltchannel, /* channel */ IO$_TTY_PORT|IO$M_LT_QUE_CHG_NOTIF, /* function */ q_iosb, /* iosb */ 0, /* astadr */ 0, /* astprm */ queue_pos_change, /* P1 = ast routine */ 0, 0, 0, 0, 0); /* P2 through P6 not used */

When a queue position change occurs, the AST routine is called with a 32-bit value. If this value is 0, then the LAT connect $QIO is about to complete, if it has not already. If the value is not 0, the lower word of 16 bits indicates the service queue position, and the upper word of 16 bits indicates the node queue position.

5.4.4.9 Hangup Notification

To allow notification by the terminal driver of abnormal termination during I/O operations, enable a Ctrl/Y AST on the channel. This ensures that the terminal driver notifies application programs of an abnormal connection termination. Note that the operating system does not return an AST parameter to the Ctrl/Y AST routine.

When an application with a pending read or write request has an abnormal LAT connection completion, the terminal driver returns a SS$_HANGUP status in the first word of the IOSB. The reason for the abnormal LAT connection completion can be attained with a LAT SENSEMODE QIO request to the port. Search the resulting P1 itemlist for the value corresponding to the LAT$_ITM_DISCONNECT_REASON item code. The value is either a LAT reject code or a LAT facility message. The LAT$V_SENSE_FULL bit must be set in the P3 parameter in order to receive this information.

If IOSB indicates an abnormal completion (SS$_ABORT, see Table 5-30) on a IO$M_LT_CONNECT modifier QIO, the LAT port driver returns the reason for the abnormal completion in IOSB+2. The reason can also be attained with the LAT SENSEMODE QIO function.

5.4.5 Sense Mode and Sense Characteristics

The sense mode and sense characteristics functions sense the characteristics of the terminal and return them to the caller in the I/O status block. The following function codes are provided:

• IO$_SENSEMODE
• IO$_SENSECHAR

IO$_SENSEMODE returns the temporary characteristics of the terminal (the characteristics associated with the current process), and IO$_SENSECHAR returns the permanent characteristics of the terminal. IO$_SENSEMODE is a logical I/O function and requires no privilege. IO$_SENSECHAR is a physical I/O function and requires the privilege necessary to perform physical I/O.

These function codes take the following device- or function-dependent arguments:

• P1---Address of a characteristics buffer
• P2---Length of characteristics buffer (default length is 8 bytes)
  For remote terminals, specify a P2 value of 8 or 12 only.

The P1 argument points to a variable-length block, as shown in Figure 5-11.

Figure 5-11 Sense Mode Characteristics Buffer

In the buffer, the device class is DC$_TERM, which is defined by the $DCDEF macro. The terminal type is defined by the $TTDEF macro, such as TT$_LA36. The maximum entry for the buffer size (page width) is 255. Table 5-5 lists the values for terminal characteristics. Table 5-6 lists the extended terminal characteristics. Characteristics values are defined by the $TTDEF macro.

The sense mode and sense characteristics functions can take the type-ahead count, read modem, and broadcast function modifiers described in the following sections.

5.4.5.1 Type-ahead Count Function Modifier

The type-ahead count function modifier returns the count of characters presently in the type-ahead buffer and a copy of the first character in the buffer. In this case, the P1 argument points to a characteristics buffer returned by IO$M_TYPEAHDCNT. Figure 5-12 shows the format of this buffer.

Figure 5-12 Sense Mode Characteristics Buffer (type-ahead)

The read modem function modifier allows access to controller-dependent information. The following combinations of function code and modifier are provided:

• IO$_SENSEMODE!IO$M_RD_MODEM
• IO$_SENSECHAR!IO$M_RD_MODEM

These function code modifier pairs take the following device- or function-dependent argument:

• P1---The address of a quadword block

Figure 5-13 shows the format of this block.

Figure 5-13 Sense Mode P1 Block

The receive modem field returns the value of the current input modem signals. Any or all of the following signals can be returned:

• TT$M_DS_DSR---Data set ready (DSR)
• TT$M_DS_RING---Calling indicator (RING)
• TT$M_DS_CARRIER---Data channel received line signal detector (CARRIER)
• TT$M_DS_CTS---Ready for sending (CTS)
• TT$M_DS_SECREC---Received backward channel data (Sec RxD)

The $TTDEF macro defines the symbols for the receive modem field.

The controller type field returns the type of terminal controller in use by the currently active terminal line. The $DCDEF macro defines the symbols for the following types of controllers:

• DT$_DZ11---DZ11 and DZV11
• DT$_DZ32---DZ32
• DT$_DMF32---DMF32
• DT$_DMB32---DMB32
• DT$_DMZ32---DMZ32
• DT$_DHV---DHV11
• DT$_DHU---DHU11
• DT$_LAT---LAT server

The broadcast function modifier returns those bits that have been set by the set mode function modifier IO$M_BRDCST (see Table 5-12 in Section 5.4.3.6). The following combination of function code and modifier is provided:

• IO$_SENSEMODE!IO$M_BRDCST

This function code modifier pair takes the following device- or function-dependent arguments:

• P1---A buffer that contains the bits that specify the requester IDs to be broadcast. (If the bit is set in the first longword, that particular command is turned off for broadcast.)
• P2---The length of the P1 buffer.

The I/O status block (IOSB) formats for the read, write, set mode, set characteristics, sense mode, sense characteristics, and LAT port driver I/O functions are shown in Figures 5-14, 5-16, 5-17, and 5-18. Figure 5-15 shows the IOSB format for the itemlist read function. Appendix A lists the status returns for these functions. (The OpenVMS system messages documentation provides explanations and suggested user actions for these returns.)

In Figure 5-14, the offset to terminator at IOSB+2 is the count of characters before the terminator character (see Section 5.4.1.2). The terminator character is in the buffer at the offset specified in IOSB+2. When the buffer is full, the offset at IOSB+2 is equal to the requested buffer size. At the same time, IOSB+4 is equal to 0. In the case of multiple character escape sequences that act as terminators, the terminator at IOSB+4 is the first character (ESC) of the escape sequence. IOSB+6 contains the size of the terminator string, usually 1. However, in an escape sequence, IOSB+6 contains the size of the validated escape sequence (see Section 5.2.1.4). The sum of IOSB+2 and IOSB+6 is the number of characters in the buffer.

Figure 5-14 IOSB Contents---Read Function

In Figure 5-15 the terminator position word contains a number, the character of which is determined by the mode of operation. For itemlist read operations that do not specify TRM$K_EM_RDVERIFY, this word contains the number of characters from the end of the buffer to the cursor location at the time the terminator character was received. If TRM$K_EM_RDVERIFY is specified, the terminator position word contains the offset into the buffer from the nonverified character.

Figure 5-15 IOSB Contents---Itemlist Read Function

The byte at IOSB+5 passes the status information, listed in Table 5-31, on TRM$K_EM_RDVERIFY operations in which TRM$M_TM_ARROWS or TRM$M_TM_TOGGLE is set in TRM$_MODIFIERS.

Table 5-31 Byte IOSB+5 Status Information

Bit	Interpretation
7 (sign bit)	0 to indicate rest of bits valid. This applies to insert/overstrike and arrow key read verify functionality only.
6--2	Always 0 if bit 7 is equal to 0. Not used; reserved for future use.
1 TRM$V_ST_OTHERWAY	Set to indicate that read is terminated in left-justify insert mode or right-justify overstrike mode.
0 TRM$V_ST_FIELD_FULL	Read terminated on an auto-tab field full condition. IOSB+7 contains an index to the cursor.

In Figure 5-16, the remote terminal driver does not return the number of lines output or the cursor position.

Figure 5-16 IOSB Contents---Write Function

In Figure 5-17, the TTdriver attempts to return the correct data in IOSB after a SETMODE or SETCHAR. To be sure the returned data is correct, the user should follow the SETMODE or SETCHAR with a SENSEMODE or SENSECHAR.

Figure 5-17 IOSB Contents---Set Mode, Set Characteristics, Sense Mode, and Sense Characteristics Functions

When an application program makes an I/O request for a connection to a remote device on a terminal server, the LAT port driver places status information about the request into the first word of the I/O status block, as shown in Figure 5-18. Table 5-30 lists the possible status returns.

If the server rejects the request, the LAT port driver returns a numeric LAT rejection code in the second word of the I/O status block. Table 5-32 lists the LAT rejection codes.

Figure 5-18 IOSB Contents---LAT Port Driver Function

Table 5-32 LAT Rejection Codes

Value	Reason
0	Reason is unknown.
1	User requested disconnect.
2	System shutdown in progress.
3	Invalid slot received.
4	Invalid service class received.
5	Insufficient resources to satisfy request.
6	Service in use.
7	No such service.
8	Service is disabled.
9	Service is not offered on the requested port.
10	Port name is unknown.
11	Invalid password.
12	Entry is not in queue.
13	Immediate access rejected (server queue full).
14	Access denied (group code mismatch).
15	Corrupted solicit request.
16	COMMAND_TYPE code is illegal/not supported.
17	Start slot cannot be sent.
18	Queue entry deleted by local node.
19	Inconsistent or illegal request parameters.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6136PRO_023.HTML