| Previous | Contents | Index |
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:
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.
| 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.
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.
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.
| 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:
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. |
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"
|
Table 3-3 shows the valid connection string parameters associated with the DECnet communications tool.
| 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:
|
| 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. |
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" |
When using the DECnet communications tool, you must start DECnet on the Macintosh system before attempting to communicate with the DIGITAL ACMS system. |
Table 3-4 shows the valid connection string parameters associated with the MacTCP communications tool.
| Parameter | Explanation |
|---|---|
| BufferSize size |
Buffer size for the communications tool. You can express the size in
either bytes or kilobytes. For example:
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. |
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" |
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.
| 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:
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. |
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 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.
| 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:
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:
|
| 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. |
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 |