HP OpenVMS Systems Documentation

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

Before the application port can be used, it must be mapped to a remotenode name, and either the port name or the service name of the remoteterminal server port. (These names must be defined locally on theterminal server.) The application port is mapped with theIO$M_LT_SETMODE modifier, specifying the following items in the P1itemlist 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 byspecifying the LAT$_ITM_QUEUED item in the P1 itemlist parameter. Validvalues 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 operatingsystem, application programs can make use of LAT application servicesthat allow terminal server users (or users on sytems with outgoingconnections) to connect to a specialized application. To do this, thesystem manager must create LAT ports that are dedicated to a particularapplication service. (Alternatively, this LAT port creation can be donefrom a program using the QIOs discussed in previous sections, providingOPER privilege.) When the remote user makes the connection to theapplication service, the connection is directly to the applicationprogram that controls a LAT port (LTA device) associated with theservice. In this case the prompt, Username:, is not received. Compaqrecommends 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 thatprovides the time of day. For this example, the system manager includesthe following lines in LAT$SYSTARTUP.COM (or enters them manually inthe LATCP program):

CREATE SERVICE TIME/ID="At the tone, the time will be"/APPLICATIONCREATE PORT LTA99:/DEDICATEDSET PORT LTA99:/SERVICE=TIME

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

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

5.4.4.7 Programming Forward Ports

An outbound LAT connection to a remote service node can be made using aforward port. The LAT port driver can connect to a remote service nodeonly if outgoing connections are enabled on the local node. Outgoingconnections can be enabled with LATCP or with a LAT SETMODE QIO to thelocal node. In addition, user group codes on the local node must matchthe service group codes of the service to which they are beingconnected. LATCP can list the services to which the local node canconnect. (Refer to 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. Theforward port is mapped with the IO$M_LT_SETMODE modifier, specifyingthe 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 ifthe port name is not specified in the P4 parameter. In other words, theLAT SETMODE QIO must be to the port corresponding to the CHAN parameter(the forward port attained by assigning a channel to _LTA0:). Note thatSS$_NOPRIV is returned if you attempt to change the port type byspecifying the LAT$_ITM_PORT_TYPE item code in the P1 itemlistparameter. If the P4 parameter is specified, the LAT port driver alsoreturns SS$_NOPRIV.

Table 5-30 lists the conditions that can occur when an applicationprogram issues an IO$M_LT_CONNECT request for a connection to a remoteservice node. The QIO request is completed when a session isestablished with the service node. Once the connection completes, datacan be read and written to the port with the QIO read and writefunctions.

5.4.4.8 Queue Change Notification (Alpha Only)

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

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

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

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

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

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 a32-bit value. If this value is 0, then the LAT connect $QIO is about tocomplete, if it has not already. If the value is not 0, the lower wordof 16 bits indicates the service queue position, and the upper word of16 bits indicates the node queue position.

5.4.4.9 Hangup Notification

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

When an application with a pending read or write request has anabnormal LAT connection completion, the terminal driver returns aSS$_HANGUP status in the first word of the IOSB. The reason for theabnormal LAT connection completion can be attained with a LAT SENSEMODEQIO request to the port. Search the resulting P1 itemlist for the valuecorresponding to the LAT$_ITM_DISCONNECT_REASON item code. The value iseither a LAT reject code or a LAT facility message. TheLAT$V_SENSE_FULL bit must be set in the P3 parameter in order toreceive 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 thereason for the abnormal completion in IOSB+2. The reason can also beattained with the LAT SENSEMODE QIO function.

5.4.5 Sense Mode and Sense Characteristics

The sense mode and sense characteristics functions sense thecharacteristics of the terminal and return them to the caller in theI/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), andIO$_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 privilegenecessary to perform physical I/O.

These function codes take the following device- or function-dependentarguments:

• 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 inFigure 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 asTT$_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 thetype-ahead count, read modem, and broadcast function modifiersdescribed in the following sections.

5.4.5.1 Type-ahead Count Function Modifier

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

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

The read modem function modifier allows access to controller-dependentinformation. The following combinations of function code and modifierare provided:

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

These function code modifier pairs take the following device- orfunction-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 modemsignals. 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 inuse by the currently active terminal line. The $DCDEF macro defines thesymbols 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 setby the set mode function modifier IO$M_BRDCST (see Table 5-12 inSection 5.4.3.6). The following combination of function code and modifieris provided:

• IO$_SENSEMODE!IO$M_BRDCST

This function code modifier pair takes the following device- orfunction-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, setcharacteristics, sense mode, sense characteristics, and LAT port driverI/O functions are shown in Figures 5-14, 5-16,5-17, and 5-18. Figure 5-15 shows the IOSB formatfor the itemlist read function. Appendix A lists the status returnsfor these functions. (The OpenVMS system messages documentationprovides explanations and suggested user actions for these returns.)

In Figure 5-14, the offset to terminator at IOSB+2 is the count ofcharacters before the terminator character (see Section 5.4.1.2). Theterminator character is in the buffer at the offset specified inIOSB+2. When the buffer is full, the offset at IOSB+2 is equal to therequested buffer size. At the same time, IOSB+4 is equal to 0. In thecase of multiple character escape sequences that act asterminators, the terminator at IOSB+4 is the first character (ESC) ofthe escape sequence. IOSB+6 contains the size of the terminator string,usually 1. However, in an escape sequence, IOSB+6 contains the size ofthe validated escape sequence (see Section 5.2.1.4). The sum of IOSB+2and 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, thecharacter of which is determined by the mode of operation. For itemlistread operations that do not specify TRM$K_EM_RDVERIFY, this wordcontains the number of characters from the end of the buffer to thecursor location at the time the terminator character was received. IfTRM$K_EM_RDVERIFY is specified, the terminator position word containsthe 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 inTable 5-31, on TRM$K_EM_RDVERIFY operations in which TRM$M_TM_ARROWSor TRM$M_TM_TOGGLE is set in TRM$_MODIFIERS.

In Figure 5-16, the remote terminal driver does not return the numberof 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 inIOSB after a SETMODE or SETCHAR. To be sure the returned data iscorrect, the user should follow the SETMODE or SETCHAR with a SENSEMODEor 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 aremote device on a terminal server, the LAT port driver places statusinformation about the request into the first word of the I/O statusblock, as shown in Figure 5-18. Table 5-30 lists thepossible status returns.

If the server rejects the request, the LAT port driver returns anumeric 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