DIGITAL TP Desktop Connector
for ACMS
Gateway Management Guide


Previous Contents Index


Chapter 3
Using Transports

This chapter discusses the TP Desktop Connector methodology for using transports, the Macintosh Communications Toolbox, and the following transports available to TP Desktop Connector:

Refer to Chapter 4 for the description of the serial transport for the Macintosh.

The sections on the Macintosh Communications Toolbox provide information on the following communications tools:

3.1 TP Desktop Connector Transport Methodology

This section outlines the transport methodologies that TP Desktop Connector applications use, giving a general understanding of why specific steps are taken in later sections.

3.1.1 Using Static-Link Libraries

TP Desktop Connector applications that use static-link libraries include:

The object libraries shipped for these clients include a transport object module. This transport object module is a layer between TP Desktop Connector and the transport. When the application is linked, the transport object becomes part of the client application executable. A single application executable can use only one transport. However, a particular application can be linked to produce different application executables that use different transports requiring different transport software.

To build an application that uses a transport other than the default transport, you must first remove the transport object from the TP Desktop Connector object library. You then place the desired transport object into the object library. You can now link an application using the chosen transport.

Certain transports have options that are not part of the standard transport software layer. These options typically define gateway connection parameters. You set these transport-specific options as environmental variables when you run the application. You can set these environmental variables either by the operating system or the program that uses the TP Desktop Connector API.

3.1.2 Default Network Transports for Client API Libraries

The client API static link libraries and samples, by default, use the network transports listed in Table 3-1. If a different transport is desired, the libraries must be reconfigured and the samples rebuilt to use that transport.

Table 3-1 Default Network Transports
Desktop System Client API Libraries Samples
DOS DECnet DECnet
OpenVMS DECnet DECnet
DIGITAL UNIX TCP/IP TCP/IP

The Macintosh samples allow the user to choose whatever transport is available without the need to reconfigure or rebuild.

3.1.3 Using Microsoft Windows Dynamic-Link Libraries

Dynamic-link libraries (DLLs) differ from static-link libraries in that you link DLLs with applications at run time, rather than when you build the application.

Note

Windows 3.1 applications that use TCP/IP, NetWare, or serial communications must use DLLs. Windows applications that use DECnet can use DLLs or static-link libraries.

If you are using a third-generation language (3GL) to code your application, you specify in your application the name of a DLL where a specific function is located. This is done in the application's module definition file or an import library.

Other methods exist for specifying the existence of DLLs, depending upon the application development environment. For example in Microsoft Visual Basic, you specify the DLL name as part of the routine declaration. At run time, Windows uses the DLL name specified by the application to locate the DLL and invoke the function. Windows searches the current directory and then all the directories listed in the PATH environmental variable until a DLL with the required name is found. When Windows finds the DLL, it is loaded and you can invoke the functions provided by it.

Each TP Desktop Connector application using DLLs requires:

In the DLL Windows 3.1 sample in the TP Desktop Connector kit, the module definition file specifies that TP Desktop Connector functions can be found in the DLL called ACMSDI.DLL. To switch network transports without relinking the application, rename any of the transport-specific TP Desktop Connector DLLs to ACMSDI.DLL. For example, if you rename the NetWare-specific TP Desktop Connector DLL (ACMSDINW.DLL) to ACMSDI.DLL, the application accesses the NetWare version of the TP Desktop Connector services at run time.

Alternatively, you can modify the name of the TP Desktop Connector DLL in the module definition file. For example, you can modify the module definition file to look for ACMSDINW.DLL. Once you relink the application, it looks for the TP Desktop Connector functions in the DLL called ACMSDINW.DLL.

3.2 Macintosh Communications Toolbox

The Macintosh implementation of TP Desktop Connector uses the Macintosh Communications Toolbox. The Communications Toolbox allows the calling application to provide connection information that indicates the transport (communications tool) to be used. You pass this connection information to TP Desktop Connector through the DBInit routine. The Communications Toolbox then loads the required software to provide a connection to the gateway.

This method requires the application to either have information about which transport is to be used, or have the application user indicate the transport to be used.

TP Desktop Connector supports five communications tools for the Macintosh:

You specify the communications tool in the connection string argument passed to the DDEV through DBInit calls.

Note

Because communications tool names contain embedded blank characters, you must enclose them in double quotation marks.

See the description of the Macintosh DBInit client service in DIGITAL TP Desktop Connector for ACMS Client Services Reference Manual for information on specifying the connection string.

3.2.1 AppleTalk-DECnet Tool

The preparations for using AppleTalk-DECnet tool on the Macintosh are the same as the preparations for using DECnet. For information on using the AppleTalk-DECnet gateway, refer to the PATHWORKS for Macintosh documentation. Table 3-2 shows the valid connection string parameters associated with the AppleTalk-DECnet communications tool.

Table 3-2 AppleTalk-DECnet Tool Parameters
Parameter Explanation
"AppleTalk-DECnet Tool" The communications tool name. This is a required parameter and must be the first parameter in the string.
BufferSize size Buffer size for the communications tool. You can express the size in either bytes or kilobytes. For example:
  • BufferSize 3500 --- specifies 3500-byte buffers
  • BufferSize 4k --- specifies 4096-byte buffers
  • BufferSize 2K --- specifies 2048-byte buffers

The default buffer size is 1024 bytes.

IntegrityCheck Applies cyclic redundancy checking (CRC) to all communications messages. This parameter has no associated value. Its presence in the connection string activates CRC; its absence indicates that CRC is not to be activated.

CRC integrity checking helps to assure that buffers are not corrupted during network transmission. However, CRC causes some performance degradation.

GatewayName name The name of the AppleTalk-DECnet Transport gateway. This parameter is required only if you do not want to use the default gateway currently set for your Macintosh. The DBInit function sets the default gateway name to name.
ZoneName name The name of the AppleTalk zone in which the AppleTalk-DECnet Transport gateway resides. This parameter is required only if you want to use a gateway that is not in the default zone currently set for your Macintosh.
Object identifier The DECnet object identifier assigned to the gateway. The default object identifier is 87.
TimeOut seconds The number of seconds that you want the DDEV to attempt to establish a communications link to the gateway. If the link has not been established within the number of seconds specified, the DDEV aborts the attempt and returns an error message. The default is 60 seconds. A value of --1 indicates that the DDEV does not check for time-out expiration. A value of 0 is invalid.

Note

For the BufferSize parameter, the minimum buffer size is 1024 bytes, and the maximum buffer size is 32 764 bytes. The MacTCP tool requires a buffer size large enough to contain all of the workspaces that may be sent or received, plus additional space for alignment and headers. To insure that you have enough space, add the sizes of all the workspaces and increase that total by 200 bytes. Use this sum as the buffer size.

Example 3-1, written in C, illustrates a connection string specifying the AppleTalk-DECnet Tool with all parameters included.

Example 3-1 AppleTalk-DECnet Connection String

  #define connstr "\p\"AppleTalk-DECnet Tool\"        \ 
                       GatewayName \"DECnet on NODEA\" \ 
                      ZoneName Boston                 \
                      Object 92                       \    
                      TimeOut 30                      \
                      BufferSize 2K                   \
                      IntegrityCheck" 

3.2.2 DECnet Tool

Table 3-3 shows the valid connection string parameters associated with the DECnet communications tool.

Table 3-3 DECnet Tool Parameters
Parameter Explanation
"DECnet Tool" The communications tool name. This is a required parameter and must be the first parameter in the string.
BufferSize size Buffer size for the communications tool. You can express the size in either bytes or kilobytes. For example:
  • BufferSize 3500 --- specifies 3500-byte buffers
  • BufferSize 4k --- specifies 4096-byte buffers
  • BufferSize 2K --- specifies 2048-byte buffers
IntegrityCheck Applies cyclic redundancy checking (CRC) to all communications messages. This parameter has no associated value. Its presence in the connection string activates CRC; its absence indicates that CRC is not to be activated.

CRC integrity checking helps to assure that buffers are not corrupted during network transmission. However, CRC causes some performance degradation.

Object identifier The DECnet object identifier assigned to the gateway. The default object identifier is 87.
TimeOut seconds The number of seconds that you want the DDEV to attempt to establish a communications link to the gateway. If the link has not been established within the number of seconds specified, the DDEV aborts the attempt and returns an error message. The default is 60 seconds. A value of --1 indicates that the DDEV does not check for time-out expiration. A value of 0 is invalid.

Note

For the BufferSize parameter, the minimum buffer size is 1024 bytes, and the maximum buffer size is 32 764 bytes. Some communications tools require more stringent limitations to the maximum buffer size.

The following example, written in C, illustrates a connection string specifying the DECnet Tool:


  #define connstr "\p\"DECnet Tool\" Object DBGS1 TimeOut 25 IntegrityCheck" 

Note

When using the DECnet communications tool, you must start DECnet on the Macintosh system before attempting to communicate with the DIGITAL ACMS system.

3.2.3 MacTCP Tool

Table 3-4 shows the valid connection string parameters associated with the MacTCP communications tool.

Table 3-4 MacTCP Tool Parameters
Parameter Explanation
BufferSize size Buffer size for the communications tool. You can express the size in either bytes or kilobytes. For example:
  • BufferSize 3500 --- specifies 3500-byte buffers
  • BufferSize 4k --- specifies 4096-byte buffers
  • BufferSize 2K --- specifies 2048-byte buffers

The default buffer size is 1024 bytes.

IntegrityCheck Applies cyclic redundancy checking (CRC) to all communications messages. This parameter has no associated value. Its presence in the connection string activates CRC; its absence indicates that CRC is not to be activated.

CRC integrity checking helps to assure that buffers are not corrupted during network transmission. However, CRC causes some performance degradation.

"MacTCP Tool" The communications tool name. This is a required parameter and must be the first parameter in the string.
RemoteTCPPort number The remote TCP port number assigned to the gateway. The default TCP port number is 1023.
TimeOut seconds The number of seconds that you want the DDEV to attempt to establish a communications link to the gateway. If the link has not been established within the number of seconds specified, the DDEV aborts the attempt and returns an error message. The default is 60 seconds. A value of --1 indicates that the DDEV does not check for time-out expiration. A value of 0 is invalid.

Note

For the BufferSize parameter, the minimum buffer size is 1024 bytes, and the maximum buffer size is 32 764 bytes. Some communications tools require more stringent limitations to the maximum buffer size.

The following example, written in C, illustrates a connection string specifying the MacTCP Tool:


  #define connstr "\p\"MacTCP Tool\" RemoteTCPPort 1022 TimeOut 120 IntegrityCheck" 

3.2.4 AppleTalk ADSP Tool

The AppleTalk ADSP Tool provides network communications through the AppleTalk Data Stream Protocol (ADSP) directly to the host ACMS node with no need for the AppleTalk-DECnet Gateway. The gateway accepts ADSP connections. The host system must have PATHWORKS AppleTalk Version 3.1 for OpenVMS Transport or higher installed.

Table 3-5 shows the valid connection string parameters associated with the ADSP Tool.

Table 3-5 AppleTalk ADSP Tool Parameters
Parameter Explanation
"AppleTalk ADSP Tool" The communications tool name. This is a required parameter and must be the first parameter in the string.
BufferSize size Buffer size for the communications tool. You can express the size in either bytes or kilobytes. For example:
  • BufferSize 3500 --- specifies 3500-byte buffers
  • BufferSize 4k --- specifies 4096-byte buffers
  • BufferSize 2K --- specifies 2048-byte buffers

The default buffer size is 1024 bytes.

IntegrityCheck Applies cyclic redundancy checking (CRC) to all communications messages. This parameter has no associated value. Its presence in the connection string activates CRC; its absence indicates that CRC is not to be activated.

CRC integrity checking helps to assure that buffers are not corrupted during network transmission. However, CRC causes some performance degradation.

TimeOut seconds The number of seconds that you want the DDEV to attempt to establish a communications link to the gateway. If the link has not been established within the number of seconds specified, the DDEV aborts the attempt and returns an error message. The default is 60 seconds. A value of --1 indicates that the DDEV does not check for time-out expiration. A value of 0 is invalid.
TypeName typename The AppleTalk type name used in the AppleTalk Name Binding Protocol. The default AppleTalk type name is "Desktop ACMS server". If you do not specify this parameter, the default is used. Do not override this default except for experimental or debugging purposes in connection with modifications to the AppleTalk name associated with the gateway.
ZoneName name The name of the AppleTalk zone in which the gateway resides. This parameter is required only if you want to access an ACMS Desktop gateway that is not in the default zone currently set for your Macintosh.

Note

For the BufferSize parameter, the minimum buffer size is 1024 bytes, and the maximum buffer size is 32 764 bytes. Some communications tools require more stringent limitations to the maximum buffer size.

3.2.5 XPC Tool

The XPC Tool is not actually a communications tool; instead, it is a name to indicate that the Macintosh system is using the X.PC protocol to provide serial communications over the telephone lines. You can use any number of serial communications tools with this feature, including the following:

Table 3-6 shows the valid connection string parameters associated with the XPC Tool.

Table 3-6 XPC Tool Parameters
Parameter Explanation
Baud rate Initializes CCL's ~BAUD variable.
BufferSize size Buffer size for the communications tool. You can express the size in either bytes or kilobytes. For example:
  • BufferSize 3500 --- specifies 3500 byte buffers
  • BufferSize 4k --- specifies 4096 byte buffers
  • BufferSize 2K --- specifies 2048 byte buffers

The default buffer size is 1024 bytes.

CCLFile name The name of the file that contains the CCL script. This parameter is required.
CCLVRefNum refnum Volume reference where the DDEV looks for the CCL file. refnum can be one of the following:
  • 0 --- default directory for the application
  • --1 --- "Connection Files" folder within the System's Extensions Folder
Code code Initializes CCL's ~CODE variable.
Dial type Initializes CCL's ~TONE variable.
IntegrityCheck Applies cyclic redundancy checking (CRC) to all communications messages. This parameter has no associated value. Its presence in the connection string indicates that CRC is to be activated. Its absence indicates that CRC is not to be activated.

CRC integrity checking helps to assure that buffers are not corrupted during network transmission. However, CRC causes some performance degradation.

ModemString string Initializes CCL's ~MSTR variable.
Pass password Initializes CCL's ~PASS variable.
PhoneNumber number Initializes CCL's ~FONE variable.
SavePassword number Determines whether password information is stored with the Calypso tool. number can be either 0 or 1. The default is 0.
ShowDebug number Controls whether a debug window is displayed. Displays all data passed to and from the underlying CTB Tool. number can be either 0 or 1. The default is 0.
ShowStatus number Tells TP Desktop Connector whether to display the Status Dialog. number can be either 0 or 1. The default is 0.
TimeOut seconds The number of seconds that you want the DDEV to attempt to establish a communications link to the gateway. If the link has not been established within the number of seconds specified, the DDEV aborts the attempt and returns an error message. The default is 60 seconds. A value of --1 indicates that the DDEV does not check for time-out expiration. A value of 0 is invalid.
Tool tool Initializes CCL's ~TOOL variable.
ToolConfig " string" Passes underlying CTB Tool configuration parameters to the tool. Any quotation mark characters within the string must be preceded by a backslash character (\). Consult the guide for individual CTB tools for supported configuration options.
User username Initializes CCL's ~USER variable.
"XPC Tool" Indicates that TP Desktop Connector is using serial communications through the telephone lines. This is a required parameter and must be the first parameter in the string.

Note

For the BufferSize parameter, the minimum buffer size is 1024 bytes, and the maximum buffer size is 32 764 bytes. Some communications tools require more stringent limitations to the maximum buffer size.

See Chapter 4 for information on connecting the Macintosh system to ACMS on OpenVMS through serial communications.


Previous Next Contents Index