• The application does not directly interfacing to the Winsock interface through the DLL.
  Instead, the application requests that diTskLnk make the Winsock request. The original application task is blocked in the DLL until the external diTskLnk task responds. While blocked, it calls the Windows Yield service. In its normal mode of operation, the acmsdiWS.dll blocks in the Winsock code, while peaking at the Windows messages to see if any can be removed for other tasks. The new level of indirection through the additional task and the changes to the blocking calls can result in differences in timing and perhaps changes in the blocking behavior that is noticeable to the calling application.
• The sharing of a connection by submitters has been disabled when using the DLL in task-link mode.
  In its normal mode of operation, the acmsdiWS.dll shares submitter sessions to the same host and port on a common transport connection. That is, if a given executable does multiple sign-ins to the same gateway, there is only one connection established that the submitters share.
  You are responsible for coordinating the use of the connection and avoiding multiple requests on the connection at the same time. This has been disabled if the acmsdiWS.dll is operating in the task-link mode, and each such session requires an independent transport connection.

The DIGITAL UNIX client supports the TCP/IP that is built into the library LIBACMSDI.A The TP Desktop Connector kit includes this code. The object code provided is listed below: To build a TCP/IP-based client, the default DECnet object is removed from the TP Desktop Connector library and replaced with the TCP/IP transport module. See DIGITAL TP Desktop Connector for ACMS Installation Guide for more information on installing client software and building the samples.

3.5.3.5 Setting Up the Environment for TCP/IP

The following sections discuss setting up the environment to use the TCP/IP transport with DOS and Macintosh clients.

3.5.3.5.1 Specifying the Gateway TCP/IP Port Number on the Client

The default TCP/IP port number used on the gateway is 1023. If the default is used, no action is necessary.

If the port TCP/IP port number 1023 is unacceptable, you can override the default by setting an environmental variable on the clients, at the system or program level. However, you must specify the same port number on the gateway as you do on the client. On a Macintosh system, you control the specification of the communications tool in the DBInit connection string.

3.5.3.5.2 Setting an Alternate TCP/IP Port Number on DOS

On DOS systems (and Microsoft Windows), you can override the default TCP/IP port number in the following manner:

C:\> SET ACMSDI_TCPIP_PORT_host=1022

where:

host is the TCP/IP name of the gateway system.

3.5.3.5.3 Setting the TCP/IP Transport on Macintosh

On Macintosh, you can set the TCP/IP transport using the PATHWORKS for Macintosh TCP/IP communications tool (MacTCP), by setting the connection string parameter to the MacTCP tool in DBInit:

#define connstr "\p\"MacTCP Tool\""

See Section 3.2.3 for information the MacTCP tool.

3.5.3.5.4 Setting an Alternate TCP/IP Port Number on Macintosh

On Macintosh, you can override the port number by setting the connection string parameter RemoteTCPPort for DBInit:

#define connstr "\p\"MacTCP Tool\" RemoteTCPPort 1022"

3.5.4 Troubleshooting the TCP/IP Transport

To insure that the gateway is listening for TCP/IP connections, perform the following steps:

1. Get information on the port that TP Desktop Connector is monitoring for connections:

   $ UCX SHOW DEVICE_SOCKET/PORT=1023/FULL Device_socket: bg2139 LOCAL REMOTE Port: 1023 0 Type: STREAM Host: 0.0.0.0 0.0.0.0 Service: RECEIVE SEND Queued I/O 0 0 Q0LEN 0 Socket buffer bytes 0 0 QLEN 0 Socket buffer quota 4096 4096 QLIMIT 5 Total buffer alloc 0 0 TIMEO 0 Total buffer limit 16384 16384 ERROR 0 Buffer or I/O waits 0 0 OOBMARK 0 Buffer or I/O drops 0 0 I/O completed 0 0 Bytes transferred 0 0 Options: ACCEPTCONN KEEPALIVE State: PRIV RCV Buff: None SND Buff: None

2. Verify that the port is owned by the gateway, using the device_socket number:

   $ SHOW DEVICE BG2139:/FULL Device BG2139: is online, mounted, network device, mailbox device. Error count 0 Operations completed 1 Owner process "ACMSDI$SERVER" Owner UIC [SOFTSUPP,SYSTEM] Owner process ID 5C000234 Dev Prot Reference count 1 Default buffer size 256

If a large number of users are connecting to the gateway using TCP/IP, you need to increase TCP/IP Services quotas. The quotas include:

• Number of device sockets
• Number of IRPs
• Internet memory buffers

See TCP/IP Services for OpenVMS System Manager's Guide for more information.

This chapter discusses using serial communications with TP Desktop Connector for ACMS. TP Desktop Connector serial communications allows Macintosh users who are not a part of a network, or are at a remote location, to access ACMS applications over a serial line without the need to manage a network or purchase networking programs. The TP Desktop Connector users hook up their Macintosh systems to modems, start scripts to attach to the gateway, and can then interact with ACMS applications.

This interface is ideal for applications such as electronic stores, because the client code can be freely distributed. The advantages of using a native PC application over a terminal emulation application include:

• Ease of use
  • Use of native PC graphical user interface (GUI)
  • Automated dialup facilities
• Better performance
  • Each keystroke is not sent to and echoed from the host system.
  • Each new form is not downloaded each time it is encountered.
  • Data can be compressed (important for slow serial links).
• Greater flexibility
  • The application can use data from both host and local system.
  • The data can be downloaded for subsequent use.

Serial connections are made through the Serial-DECnet Gateway. Figure 4-1 illustrates the connections.

Figure 4-1 Serial Connections

The following sections discuss how to prepare the gateway to use serial communications as a transport. See Section 4.2 for information about preparing the client for serial communications.

4.1.1 Installation Requirements for Serial Communications

The following components must be present on the DECnet node to which the users will attach:

• TP Desktop Connector Serial-DECnet Gateway
  The TP Desktop Connector Serial-DECnet Gateway is a detached multithreaded process, which attaches to devices. The gateway communicates with the server using the DECnet network.
• TP Desktop Connector Serial-DECnet Gateway Manager
  The TP Desktop Connector Serial-DECnet Gateway Manager passes commands to the gateway. You can use these commands to attach devices, detach devices, switch an interactive session to communicate with a TP Desktop Connector client, and so forth.
• TP Desktop Connector Gateway for ACMS
  The gateway must be running on a node in the network.

To activate the gateway for serial communications, you must have the DECnet network started as a transport, as well as the Serial-DECnet Gateway. To start the Serial-DECnet Gateway, use the following command:

$ @SYS$STARTUP:ACMSDI$SERIAL_GATE_STARTUP

This command starts a detached process ready to connect user links. You can place optional process parameters in an optional parameter file. See Section 2.5.3 for information on optional parameters.

4.1.3 Attaching Devices to the Serial-DECnet Gateway

You must attach asynchronous devices to the gateway before TP Desktop Connector can make serial connections. Attach devices to the gateway as follows:

• Attach permanently for use only by TP Desktop Connector serial connections.
• Change the current device to TP Desktop Connector serial mode and then terminate the current process.
• Change the current device to TP Desktop Connector serial mode and restart the current process when done.

Serial devices are attached to the gateway by using the TP Desktop Connector Serial-DECnet Gateway manager after the gateway has been started. Permanent connections take over the indicated device for exclusive use by TP Desktop Connector applications. Once the devices are attached permanently, the device is no longer available for use by terminals.

4.1.4 Maintaining Permanent Connections

The following example shows how to attach a device permanently leaving the baud rate unchanged:

$ RUN SYS$SYSTEM:ACMSDI$SERIAL_GATE_MANAGER ACMSDIGW$MANAGER> ATTACH TTA3:/PERMANENT

You can reserve LAT devices for permanent use with the LAT server, LATCP, and the gateway manager. On the LAT server, you must set the port for dynamic or remote access. Remote access allows only remote processes, for example, the TP Desktop Connector Serial-DECnet gateway. Dynamic access allows access to local or remote processes. For example:

local> SET PRIV password> local> set port 5 ACCESS REMOTE local> set port 5 SPEED 2400

Run the LATCP program (which requires the CMKRNL privilege) to create and initialize a terminal port, as in the following example:

$ RUN SYS$SYSTEM:LATCP LCP> CREATE PORT LTA900: LCP> SET PORT LTA900:/NODE=SWELTA/PORT=5

Now that the device is initialized and known to the OpenVMS system, you can attach to the gateway:

$ RUN SYS$SYSTEM:ACMSDI$SERIAL_GATE_MANAGER ACMSDIGW$MANAGER> ATTACH LTA900/PERMANENT

4.1.5 Switching the Current Device to TP Desktop Connector Serial Mode

If TP Desktop Connector establishes a connection as an interactive session to the host machine, you can change the device to TP Desktop Connector serial mode. You can suspend the process associated with this device for the duration of the session or you can terminate it.

For example, you can use a captive login account for terminal connections over an X.25 network. The user is an X.29 terminal accessing the host. The script can then log in to the captive account. A command file associated with this account can then have the gateway attach the device and log out the current process.

The following shows the LOGIN.COM for this account:

$! $! Attach this terminal to the Serial-DECnet Gateway $! If the user does not attach within 2 minutes $! detach the device $! $ RUN SYS$SYSTEM:ACMSDI$SERIAL_GATE_MANAGER ACMSDIGW$MANAGER> ATTACH TT:/TIMEOUT=00:02:00 $! $! Don't want this process anymore $! $ LOGOUT

An interactive user on the host might want to switch the current device to Serial-DECnet Gateway mode and then resume the current process. In this case, you must use the /SUSPEND switch to suspend the current process for the duration of the connection in serial gateway mode. The user can then do the following:

$ RUN SYS$SYSTEM:ACMSDI$SERIAL_GATE_MANAGER ACMSDIGW$MANAGER> ATTACH TT:/SUSPEND/TIMEOUT=00:01:00

The current process is then suspended until the serial gateway detaches the device. The serial gateway detaches a device under the following conditions:

• If the device is attached with the /PERMANENT switch:
  • The device is detached with the DETACH command.
  • A nonrecoverable error occurs on a read of the device.
• If the device is attached temporarily:
  • The device is detached with the DETACH command.
  • A client session is not established within the timeout period.
  • A nonrecoverable read error occurs.
  • Every client session is terminated.

TP Desktop Connector supports serial communications for Macintosh clients with ACMSDI client services. For troubleshooting Macintosh CCL scripts, see Inside CCL, from Apple Computer, Inc.

4.2.1 CCL Scripts

The Calypso Tool reads and processes the CCL scripts. Under control of the CCL script, Calypso invokes the communications tool, such as the Serial Tool, which implements the protocol.

The CCL script specifies the work necessary to establish the connection between the Macintosh client and the gateway to attach the gateway to the Serial-DECnet Gateway. After the connection is made, both Calypso and CCL remain transparent until the connection closes. The CCL script then specifies the work that is necessary to clean up the connection.

When using the Serial Tool, the CCL script performs the following functions:

1. Configures and dials the modem, typically by issuing AT commands.
2. Logs in, if dialing into a Value Added Network (VAN).
3. Logs in to the remote terminal server.
4. Connects and logs in to the remote host computer.
5. Runs ACMSDI$SERIAL_GATE_MANAGER and attaches it to the current device.
6. Terminates the current process.
7. Hangs up and resets the modem, when the gateway closes the connection.

A CCL file automates the attachment of a Macintosh client to the gateway. To accomplish this, the CCL language provides a rich command set that controls the connection and disconnection sequences. Consult the manual Inside CCL, from Apple Computer, Inc., for a complete explanation of developing CCL scripts.

The following rules apply to writing CCL scripts:

• CCL code always has only one command per line.
• CCL files have two main components: commands for the log-on sequence, and commands for the log-off sequence.
• The log-on sequence executes when the connection is being opened. The CCL file describes how the connection is to be made, and gives any special commands such as sending user names, passwords, and other log-on commands. The log-on sequence starts with --LABEL 0. Error messages are usually included in this section of code.
• The log-off sequence executes when a connection is to be closed (disconnected). The CCL file describes any special steps required for logging off. The log-off sequence begins with *--LABEL 0.

  Note All lines of code in the disconnect section MUST begin with and askterisk (*). This allows the CCL interpreter to distinguish log-off instructions from log-on instructions. --LABEL 0 and *--LABEL 0 are not the same.

• CCL provides two ways to insert comments (remarks) that the interpreter does not read:
  • Place remarks after commands.
    After most commands, you can leave two or more spaces and type the remarks on the same line. However, some commands, such as Alert, DsplyMsg, MatchStr, and XMIT, assume that all items following them are parameters and cannot have comments on the same line.
  • Place remarks on lines beginning with an exclamation point (!)
    CCL treats an entire line that begins with an exclamation point as a comment. You can also insert blank lines that start with an exclamation point.
• CCL is not case-sensitive so you can use either uppercase or lowercase letters.
• CCL uses labels to segment the code into sections:
  • Begin each section of code with a LABEL command.
  • Begin label numbers with 0.
  • Label 0 indicates to the CCL interpreter where to begin.
  • Label numbers can go up to 127.
  • Use label number 0 in both the log-on and log-off commands.
  • Begin labels and commands in the log-off sequence with an asterisk (*).
  • You can skip numbers to leave room for later expansion of the CCL file.
• You set variables, such as ~USER, ~PASS, and so on, with connection string parameters. You can reference these variables in your CCL file. The value set by the connection string replaces the variable in the script.

Table 4-1 shows the CCL script commands with a brief description of the command. Inside CCL, from Apple Computer, Inc., provides the rest of the CCL commands.

Table 4-1 CCL Script Commands

Command	Description
CTBChoose	Opens a Communications Toolbox dialog box that allows the user to set communication parameters and choose a tool from a directory of installed tools.
CTBClose	Closes the currently open Communications Toolbox connection.
CTBDown label	Checks the status of the Communications Toolbox connection and jumps to a label, if the connection is down. label is the label to which the interpreter jumps if the CTB connection is down.
CTBOpen label	Tells the interpreter to open the Communications Toolbox connection and where to go if it opens successfully. label is the label to which the interpreter jumps after the Communications Toolbox opens successfully.
CTBParam label string	Sets parameters for the Communications Toolbox tool. Here are the rules for setting parameter values: Specify the parameter name followed by its value. Set parameters on one line or on two or more lines. Set parameters in any order. Enclose a parameter value that contains spaces with quotation marks. label is the label to which the interpreter jumps if an error occurs in the execution of the string. string is one or more pairs of parameters and parameter values.
CTBTool label1 label2 flags tool	Selects a Communications Toolbox tool to use to manage the connection. label1 is the label to which the interpreter jumps if the requested tool is not installed. label2 is the label to which the interpreter jumps if any error occurs while opening the tool. flags provides the specific internal parameters for the selected tool. tool is the requested connection tool. If the flags field is 0, CCL uses the following default value: cmData+cmQuiet+cmNoMenus
IfEqJmp " token1" " token2" label	Compares two tokens and, if they are equal, jumps to a label. label is the label to which the interpreter jumps if token1 is equal to token2. For IfEqJmp and the rest of the IF xxyyy commands, the token can be any of the following: Var 1 through Var 8 or Tries Numeric constant, such as the number 10 String literal, such as "Apple" Any of the string variables, such as ~USER If either of the tokens used are numbers, the other token is compared as a number. You can surround string literals by either single or double quotation marks.
IfEqJSR " token1" " token2" label	Compares two tokens and, if they are equal, jumps into the subroutine beginning at a specified label. The subroutine returns to the command following the IfEqJSR command. label is the label to which the interpreter jumps if token1 is equal to token2. See IfEqJmp for a description of the tokens.
IfGTJmp " token1" " token2" label	Compares two tokens and, if the first token is greater than the second token, jumps to a label. label is the label to which the interpreter jumps if token1 is greater than token2. See IfEqJmp for a description of the tokens.
IfGTJSR " token1" " token2" label	Compares two tokens and, if the first token is greater than the second token, jumps into the subroutine beginning at a specified label. The subroutine returns to the command following the IfGTJSR command. label is the label to which the interpreter jumps if token1 is greater than to token2. See IfEqJmp for a description of the tokens.
IfInJmp " token1" " token2" label	Examines two tokens. If the second token is a substring of the first, the interpreter jumps to a label. label is the label to which the interpreter jumps if token2 is a substring of token1. See IfEqJmp for a description of the tokens.
IfInJSR " token1" " token2" label	Examines two tokens. If the second token is a substring of the first, the interpreter jumps into the subroutine beginning at a specified label. The subroutine returns to the command following the IfInJSR command. label is the label to which the interpreter jumps if token2 is a substring of token1. See IfEqJmp for a description of the tokens.
IfLTJmp " token1" " token2" label	Compares two tokens and, if the first token is less than the second token, jumps to a label. label is the label to which the interpreter jumps if token1 is less than token2. See IfEqJmp for a description of the tokens.
IfLTJSR " token1" " token2" label	Compares two tokens and, if the first token is less than the second token, jumps into the subroutine beginning at a specified label. The subroutine returns to the command following the IfLTJSR command. label is the label to which the interpreter jumps if token1 is less than token2. See IfEqJmp for a description of the tokens.
IfSWJmp " token1" " token2" label	Examines two tokens. If the leftmost bytes of the first token match the second token, the interpreter jumps to a label. label is the label to which the interpreter jumps if token1 starts with token2. See IfEqJmp for a description of the tokens.
IfSWJSR " token1" " token2" label	Examines two tokens. If the leftmost bytes of the first token match the second token, the interpreter jumps into the subroutine beginning at a specified label. The subroutine returns to the command following the IfSWJSR command. label is the label to which the interpreter jump if token1 starts with token2. See IfEqJmp for a description of the tokens.
IfTries number label	Compares the value of the Tries variable with an integer. Use it with the SetTries, IncTries, and DecTries commands. number is the integer with which Tries is compared. label is the label to which the interpreter jumps if the two numbers are equal.
NoCTB label	Checks to see if the Communications Toolbox is installed. With Calypso, this command never jumps. Calypso always uses the CTB. label is the label to which the interpreter jumps if the Communications Toolbox is not available.
SerClose	Closes the currently selected port immediately.