Symantec 14541094 - pcAnywhere Host &, PCANYWHERE - V 12.0 AUTOMATION GUIDE, pcAnywhere Remote Manual

Symantec pcAnywhere™
OLE Automation Guide

Symantec pcAnywhere™ OLE Automation Guide

The software described in this book is furnished under a license agreement and may be
used only in accordance with the terms of the agreement.

Documentation version 12.0

Legal Notice

Copyright © 2006 Symantec Corporation.

All rights reserved.

Federal acquisitions: Commercial Software - Government Users Subject to Standard
License Terms and Conditions.

Symantec, the Symantec Logo, and pcAnywhere are trademarks or registered trademarks
of Symantec Corporation in the United States and certain other countries. Other names
may be trademarks of their respective owners.
Microsoft, Windows, Windows NT, MS-DOS, and the Windows logo are registered
trademarks or trademarks of Microsoft Corporation.
Additional company and product names may be trademarks or registered trademarks of
the individual companies and are respectfully acknowledged.

The product described in this document is distributed under licenses restricting its use,
copying, distribution, and decompilation/reverse engineering. No part of this document
may be reproduced in any form by any means without prior written authorization of
Symantec Corporation and its licensors, if any.

THIS DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED
CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED
WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON­INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH
DISCLAIMERS ARE HELD TO BE LEGALLY INVALID, SYMANTEC CORPORATION SHALL
NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION
WITH THE FURNISHING PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE
INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE
WITHOUT NOTICE.

Symantec Corporation
20330 Stevens Creek Blvd.
Cupertino, CA 95014 USA

http://www.symantec.com

Printed in the United States of America.
10987654321

Technical Support

Symantec Technical Support maintains support centers globally. Technical
Support’s primary role is to respond to specific queries about product feature
and function, installation, and configuration. The Technical Support group also
authors content for our online Knowledge Base. The Technical Support group
works collaboratively with the other functional areas within Symantec to
answer your questions in a timely fashion. For example, the Technical Support
group works with Product Engineering and Symantec Security Response to
provide alerting services and virus definition updates.

Symantec’s maintenance offerings include the following:

■ A range of support options that give you the flexibility to select the right

■ Telephone and Web-based support that provides rapid response and up-to-

■ Upgrade insurance that delivers automatic software upgrade protection

■ Global support that is available 24 hours a day, 7 days a week worldwide.

amount of service for any size organization

the-minute information

Support is provided in a variety of languages for those customers that are
enrolled in the Platinum Support program

■ Advanced features, including Technical Account Management

For information about Symantec’s Maintenance Programs, you can visit our
Web site at the following URL:

www.symantec.com/techsupp/ent/enterprise.html

Select your country or language under Global Support. The specific features that
are available may vary based on the level of maintenance that was purchased
and the specific product that you use.

Contacting Technical Support

Customers with a current maintenance agreement may access Technical
Support information at the following URL:

www.symantec.com/techsupp/ent/enterprise.html

Select your region or language under Global Support.

Before contacting Technical Support, make sure you have satisfied the system
requirements that are listed in your product documentation. Also, you should be
at the computer on which the problem occurred, in case it is necessary to
recreate the problem.

When you contact Technical Support, please have the following information
available:

■ Product release level

■ Hardware information

■ Available memory, disk space, NIC information

■ Operating system

■ Version and patch level

■ Network topology

■ Router, gateway, and IP address information

■ Problem description:

■ Error messages and log files

■ Troubleshooting that was performed before contacting Symantec

■ Recent software configuration changes and network changes

Licensing and registration

If your Symantec product requires registration or a license key, access our
technical support Web page at the following URL:

Customer service

www.symantec.com/techsupp/ent/enterprise.html.

Select your region or language under Global Support, and then select the
Licensing and Registration page.

Customer service information is available at the following URL:

www.symantec.com/techsupp/ent/enterprise.html

Select your country or language under Global Support.

Customer Service is available to assist with the following types of issues:

■ Questions regarding product licensing or serialization

■ Product registration updates such as address or name changes

■ General product information (features, language availability, local dealers)

■ Latest information about product updates and upgrades

■ Information about upgrade insurance and maintenance contracts

■ Information about Symantec Value License Program

■ Advice about Symantec's technical support options

■ Nontechnical presales questions

■ Issues that are related to CD-ROMs or manuals

Maintenance agreement resources

If you want to contact Symantec regarding an existing maintenance agreement,
please contact the maintenance agreement administration team for your region
as follows:

■ Asia-Pacific and Japan: [e-mail]

■ Europe, Middle-East, and Africa: [e-mail]

■ North America and Latin America: [e-mail]

Additional enterprise services

Symantec offers a comprehensive set of services that allow you to maximize
your investment in Symantec products and to develop your knowledge,
expertise, and global insight, which enable you to manage your business risks
proactively. Additional services that are available include the following:

Symantec Early Warning
Solutions

Managed Security
Services

Consulting services Symantec Consulting Services provide on-site technical

Educational Services These services provide a full array of technical training,

These solutions provide early warning of cyber attacks,
comprehensive threat analysis, and countermeasures to
prevent attacks before they occur.

These services remove the burden of managing and monitoring
security devices and events, ensuring rapid response to real
threats.

expertise from Symantec and its trusted partners. Symantec
Consulting Services offer a variety of prepackaged and
customizable options that include assessment, design,
implementation, monitoring and management capabilities,
each focused on establishing and maintaining the integrity and
availability of your IT resources.

security education, security certification, and awareness
communication programs.

To access more information about Enterprise Services, please visit our Web site
at the following URL:

www.symantec.com

Select your country or language from the site index.

Contents

Chapter 1 Using OLE Automation with Symantec pcAnywhere

About OLE Automation ....................................................................................... 11

About the pcAnywhere Automation Server .................................................... 12

What you can do with the pcAnywhere Automation Server ........................12

Before you start ....................................................................................................13

Automatically registering the remote engine ......................................... 13

Manually registering the remote engine ..................................................14

Accessing the pcAnywhere Automation Server ..................................... 14

Accessing the pcAnywhere Automation Server with Visual Basic ......14

Accessing the pcAnywhere Automation Server with Visual C++ ........15

Launching host and remote OLE objects .................................................. 17

Where to find more information ....................................................................... 17

Chapter 2 Visual Basic object definitions

About Visual Basic objects ..................................................................................19

CRemoteDataManager methods ........................................................................ 20

CurrentDirectory() .......................................................................................20

ChangeDirectory(NewDirectory) ...............................................................21

FindFirst(Pattern, Name string) ................................................................21

FindNext(Name) ........................................................................................... 22

RetrieveObject(Name, AccessMode, Password) ......................................23

RetrieveObjectEx(Name, AccessMode, Password) .................................. 23

CreateObject(Name) .....................................................................................24

CreateObjectEx(Name) ................................................................................24

DeleteObject(Name, Password) .................................................................. 25

CRemoteData properties ....................................................................................26

Connection type properties ........................................................................28

Dialing properties ........................................................................................ 30

COM device properties ................................................................................ 31

NetBIOS device properties .........................................................................34

ISDN via CAPI 2.0 device properties ......................................................... 35

CRemoteDataEx object ........................................................................................36

Visual Basic sample code for remote functionality ................................ 37

8 Contents

CHostDataManager methods .............................................................................39

CurrentDirectory() .......................................................................................39

FindFirst(Pattern, Name string) ................................................................ 39

FindNext(Name) ........................................................................................... 40

RetrieveObject(Name, AccessMode, Password) ...................................... 41

RetrieveObjectEx(Name, AccessMode, Password) .................................. 41

CreateObject(Name) .....................................................................................42

CreateObjectEx(Name) ................................................................................42

DeleteObject(Name, Password) .................................................................. 43

Launch(Name) .............................................................................................. 43

CHostData properties ..........................................................................................44

Connection type properties ........................................................................ 46

AssignConnection(ConnectionType) method ..........................................48

UnassignConnection(ConnectionType) method ..................................... 48

Dialing properties ........................................................................................ 49

COM device properties ................................................................................ 50

NetBIOS device properties ......................................................................... 53

ISDN via CAPI 2.0 device properties ......................................................... 54

CHostDataEx object .............................................................................................55

Visual Basic sample code for host functionality ..................................... 62

Awrem32 functions ............................................................................................. 63

awConnect(FileName) ................................................................................. 63

awDisconnect() ............................................................................................. 64

FileXferFromHost(HostFile, RemoteFile) ................................................64

FileXferToHost(HostFile, RemoteFile) ..................................................... 65

CreateFolderOnHost(FolderName) ...........................................................65

ExecuteHostFile(FileName) ........................................................................66

GetError() ...................................................................................................... 66

ConnectionStatus() ......................................................................................67

Chapter 3 Visual C++ object definitions

About Visual C++ objects .................................................................................... 69

CRemoteDataManager methods ........................................................................ 71

BSTR CurrentDirectory(); ...........................................................................71

BOOL ChangeDirectory(LPCTSTR lpszNewDirectory); .........................71

BOOL FindFirst(LPCTSTR lpszPattern, BSTR FAR*

pbstrFullQualName); ........................................................................... 72

BOOL FindNext(BSTR FAR* pbstrFullQualName); .................................72

LPDISPATCH RetrieveObject(LPCTSTR lpszFQName, short

wAccessMode, LPCTSTR lpszPassword); ......................................... 73

LPDISPATCH RetrieveObjectEx(LPCTSTR lpszFQName, short

wAccessMode, LPCTSTR lpszPassword); ......................................... 73

LPDISPATCH CreateObject(LPCTSTR lpszFQName); ............................74

LPDISPATCH CreateObjectEx(LPCTSTR lpszFQName); ........................ 75

BOOL DeleteObject(LPCTSTR lpszFQName, LPCTSTR

lpszPassword); ...................................................................................... 76

BOOL Launch(LPCTSTR lpszFQName); ....................................................76

CRemoteData object ............................................................................................77

Get and Set methods ...................................................................................77

Remote object Detail methods ...................................................................79

Remote object methods ...............................................................................82

CRemoteDataEx object ........................................................................................85

Visual C++ sample code for remote functionality .................................. 85

CHostDataManager methods .............................................................................86

BSTR CurrentDirectory(); ...........................................................................86

BOOL ChangeDirectory(LPCTSTR lpszNewDirectory); .........................86

BOOL FindFirst(LPCTSTR lpszPattern, BSTR FAR*

pbstrFullQualName); ........................................................................... 87

BOOL FindNext(BSTR FAR* pbstrFullQualName); .................................87

LPDISPATCH RetrieveObject(LPCTSTR lpszFQName, short

wAccessMode, LPCTSTR lpszPassword); ......................................... 88

LPDISPATCH RetrieveObjectEx(LPCTSTR lpszFQName, short

wAccessMode, LPCTSTR lpszPassword); ......................................... 89

LPDISPATCH CreateObject(LPCTSTR lpszName); .................................90

LPDISPATCH CreateObjectEx(LPCTSTR lpszName); ............................. 90

BOOL DeleteObject(LPCTSTR lpszFQName, LPCTSTR

lpszPassword); ...................................................................................... 91

BOOL Launch(LPCTSTR lpszFQName); ....................................................91

CHostData object .................................................................................................92

Get and Set methods ...................................................................................92

Host object Detail methods ........................................................................93

Host object methods ....................................................................................97

9Contents

10 Contents

Index

CHostDataEx object ...........................................................................................101

Visual C++ sample code for host functionality ..................................... 103

Awrem32 functions ...........................................................................................104

boolean awConnect(BSTR FileName); ....................................................104

boolean awDisconnect(); ...........................................................................105

boolean FileXferFromHost(BSTR HostFile, BSTR RemoteFile); .........105

boolean FileXferToHost(BSTR HostFile, BSTR RemoteFile); .............. 105

boolean CreateFolderOnHost(BSTR FolderName); ...............................106

boolean ExecuteHostFile(BSTR FileName); ...........................................106

BSTR GetError(); ........................................................................................107

short ConnectionStatus(); .........................................................................107

Chapter

Using OLE Automation
with Symantec
pcAnywhere

This chapter includes the following topics:

1

■ About OLE Automation

■ About the pcAnywhere Automation Server

■ What you can do with the pcAnywhere Automation Server

■ Before you start

■ Where to find more information

About OLE Automation

OLE Automation is a technology that lets you create an external application or
other development tool (such as a script or macro) that can control and
automate any exposed function within an application.

OLE Automation consists of the following components:

■ OLE Automation server: An application or software component that exposes

its functionality so that it can be accessed or controlled by other
applications or development tools

The pcAnywhere Automation Server is an example of an OLE Automation
server.

See “About the pcAnywhere Automation Server” on page 12.

12 Using OLE Automation with Symantec pcAnywhere

About the pcAnywhere Automation Server

■ OLE Automation controller: An application or development tool that

accesses and controls the components that have been exposed by the OLE
Automation server

You can use any programming language that supports OLE Automation.
The two most common programming languages are Microsoft Visual Basic
and Microsoft Visual C++.

An external application accesses an OLE Automation server by connecting to the
server and then requesting access to one or more of its published interfaces. An
interface is an entry point that allows access to one or more related methods or
properties. After an application obtains an interface to the server, it can then
call any internal interface method as though it were part of the external
application.

About the pcAnywhere Automation Server

The pcAnywhere Automation Server lets external applications manage
pcAnywhere remote, host, and caller information files to automate remote
control and file transfer tasks. The pcAnywhere Automation Server functions as
a programmable replacement for the Symantec pcAnywhere user interface and
mirrors much of its default behavior.

For example, when you create a host object in pcAnywhere, the first available
modem TAPI device is assigned by default. Similarly, when you create a host
object using the pcAnywhere Automation Server and then enumerate through
the list of assigned connections, the first available modem TAPI device is
already assigned.

What you can do with the pcAnywhere Automation
Server

The pcAnywhere Automation Server lets you automate a variety of
administrative and productivity tasks. For example, you can do the following:

■ Automatically distribute and install software updates on multiple

computers across your network

■ Schedule automatic file transfers between computers for audit or archive

purposes

■ Automatically add a name to or remove a name from the allowed callers list

on every pcAnywhere host on your network

This document contains several examples, written in both Visual Basic and
Visual C++, to illustrate how to connect to and use the pcAnywhere Automation
Server.

See “Visual Basic object definitions” on page 19.

See “Visual C++ object definitions” on page 69.

Before you start

During a connection to the pcAnywhere Automation Server and its interfaces,
identifier parameters, known as globally unique identifiers (GUIDs), are passed
to the automation library API functions. A separate GUID is assigned to the
pcAnywhere Automation Server and to each exposed interface. These GUIDs
must be present in the system registry to connect an external application to the
pcAnywhere Automation Server and its interfaces.

You can register the GUID entries automatically if you are running the external
application on a computer on which Symantec pcAnywhere is installed.
Otherwise, you must register the GUID entries manually.

13Using OLE Automation with Symantec pcAnywhere

Before you start

See “Automatically registering the remote engine” on page 13.

See “Manually registering the remote engine” on page 14.

Automatically registering the remote engine

Before you connect to another computer for the first time using your OLE client,
you must self-register the remote engine. You can do this automatically when
you start a remote object in Symantec pcAnywhere.

To automatically register the remote engine

1 To open Symantec pcAnywhere, do one of the following:

■ On the desktop, double-click the Symantec pcAnywhere program icon.

■ On the Windows taskbar, click Start > Programs > Symantec

pcAnywhere.

2 In the pcAnywhere Manager window, click Remotes.

3 Double-click a remote connection item.

This process registers the remote engine. You do not need to complete the
connection.

14 Using OLE Automation with Symantec pcAnywhere

Before you start

Manually registering the remote engine

If pcAnywhere is not installed on the computer on which you are running the
external application, you must register the GUIDs manually by running the
pcAnywhere Automation Server executable file (Winawsvr.exe). You only need
to run the executable file once to add the GUIDs to the registry. The
Winawsvr.exe file is located in the default Symantec pcAnywhere data
directory.

Accessing the pcAnywhere Automation Server

You can access the pcAnywhere Automation Server using any language
platform that supports OLE Automation. The two most popular language
platforms that support OLE Automation are Visual Basic and Visual C++.

The coding principles for these two platforms are similar, although in the Visual
Basic environment, much of the low-level work is performed behind the scenes
by the Visual Basic run-time system.

Accessing the pcAnywhere Automation Server with Visual Basic

The Visual Basic programming language has built-in support to interact with
OLE Automation servers, such as the pcAnywhere Automation Server. You
create a Standard Exe project, and then enter code in each method to access the
pcAnywhere Automation Server. Visual Basic takes the high-level method calls
in the source files and expands them internally into the corresponding low-level
OLE Automation method calls.

See “Visual Basic object definitions” on page 19.

To access the pcAnywhere Automation Server with Visual Basic

1 Add a pair of Object variables for each pcAnywhere object that you want to

access.
For example, when working with remote objects, DIM a

RemoteDataManager and a RemoteDataObject as Object.

2 Use the RemoteDataManager to attach to the remote object’s data manager.

For example, call the CreateObject method with
WINAWSVR.REMOTEDATAMANAGER as a parameter.

Visual Basic uses the textual parameter to locate the manager’s identifier in
the registry and returns the interface to that manager.

3 Once there is a valid data manager object, use it to do any of the following:

■ Determine the current directory.

■ Change to another directory.

Before you start

■ Enumerate the associated data object files in the current directory.

■ Create, retrieve, or delete a data object file.

4 After a data object is created or retrieved, you can get or set properties of the

object.
The Visual Basic syntax does not use a property’s name to differentiate

between getting and setting its value. Instead, the property’s position in
relation to the assignment operator determines whether the underlying
method call is a Get or a Set.

The following examples demonstrate a Get and a Set:

■ To get an object’s phone number value, place the property name to the

right of the assignment operator.

For example, s = RemoteData.PhoneNumber(), where s is a string

variable.

■ To set the phone number, place the property name to the left of the

assignment operator.

For example, RemoteData.PhoneNumber = “555-1212”

15Using OLE Automation with Symantec pcAnywhere

Accessing the pcAnywhere Automation Server with Visual C++

The pcAnywhere Automation Server uses type libraries to expose information
about its interfaces and methods to automation clients that are written in Visual
C++. These type libraries use Microsoft Foundation Classes (MFC), which can be
imported into your application using the Visual C++ ClassWizard.

The data manager classes that are provided in the type libraries provide the
functionality that is needed to obtain an interface to the pcAnywhere
Automation Server and perform high-level operations on the interface’s
associated object type.

Use the data manager object to do the following:

■ Determine or change the current directory.

■ Enumerate through the list of data object files in the current directory.

■ Create, retrieve, or delete a named object.

Once created or retrieved, an object uses the associated data object class to
examine or modify any of its exposed properties. Most of these properties are
exposed through a pair of methods that begin with the word Get or Set. For
example, a user calls the GetPhoneNumber method to examine the object’s
current phone number property and calls SetPhoneNumber to set it.

See “Visual C++ object definitions” on page 69.

16 Using OLE Automation with Symantec pcAnywhere

Before you start

Importing and viewing classes

The pcAnywhere Automation Server uses the following type libraries:

■ Winawsvr.tlb: Provides the information needed to connect to the

pcAnywhere Automation Server and access its interfaces

■ Awrem32.tlb: Provides the information needed to control pcAnywhere

connections

Import and view classes

The following procedures explain how to import the class definitions from the
pcAnywhere Automation Server type libraries into your MFC application and
then view the classes that have been added to your application.

To import classes

1 In Visual C++, create an MFC application.

2 On the View menu, click Class Wizard.

3 In the Class Wizard dialog box, click Add Class, and then click From a type

library.

4 Double-click winawsvr.tlb.

5 In the Confirm Classes dialog box, click OK to import all class definitions.

6 In the Class Wizard dialog box, click Add Class, and then click From a type

library.

7 Double-click awrem32.tlb.

8 In the Confirm Classes dialog box, click OK to import all class definitions.

9 In the Class Wizard dialog box, click OK to complete the import process.

The classes are added to the application. These classes let you manipulate
objects and manage connections.

Importing the class definitions from the type libraries also adds support
files to the application. These files contain the class definitions and
implementation source code for the pcAnywhere Automation Server.

See “Viewing the class definitions and implementation files” on page 17.

To view the added classes

1 In Visual C++, open your MFC application.

2 In the Workspace window, click the ClassView tab.

Where to find more information

Viewing the class definitions and implementation files

When you import the pcAnywhere Automation Server type libraries into your
application, the following files are added:

■ Winawsvr.h

■ Winawsvr.cpp

■ Awrem32.h

■ Awrem32.cpp

These files contain the class definitions and implementation source code for the
pcAnywhere Automation Server. You do not need to edit these files; however,
each application source file that contains calls to the pcAnywhere Automation
Server methods must include Winawsvr.h.

To view the class definitions and implementation files

1 In Visual C++, open your MFC application.

17Using OLE Automation with Symantec pcAnywhere

2 In the Workspace window, click the FileView tab.

Launching host and remote OLE objects

Symantec pcAnywhere requires that you store all host and remote objects in the
default data directory. Before you launch a host or remote object that you
created using OLE, ensure that the object is located in the pcAnywhere default
data directory.

Where to find more information

For more information about OLE automation, see the following references:

■ Blaszczak, Mike. 1997. Professional MFC with Visual C++ 5. Birmingham,

UK.: Wrox Press.

■ Box, Don. 1998. Essential COM. Reading, Mass.: Addison-Wesley.

■ Brockschmidt, Kraig. 1995. Inside OLE, Second Edition. Redmond, Wash.:

Microsoft Press.

■ Horton, Ivor. 1997. Beginning MFC Programming. Birmingham, UK.: Wrox

Press.

■ Rogerson, Dale. 1997. Inside COM. Redmond, Wash.: Microsoft Press.

■ Templeman, Julian. 1997. Beginning MFC COM Programming. Birmingham,

UK.: Wrox Press.

18 Using OLE Automation with Symantec pcAnywhere

Where to find more information

Chapter

Visual Basic object
definitions

This chapter includes the following topics:

■ About Visual Basic objects

■ CRemoteDataManager methods

2

■ CRemoteData properties

■ CRemoteDataEx object

■ CHostDataManager methods

■ CHostData properties

■ CHostDataEx object

■ Awrem32 functions

About Visual Basic objects

The pcAnywhere Automation Server provides the following components to
support OLE Automation:

■ Winawsvr: Provides the information needed to connect to the pcAnywhere

Automation Server and access its interfaces

■ Awrem32: Provides the information needed to control pcAnywhere

connections

20 Visual Basic object definitions

CRemoteDataManager methods

Table 2-1 describes the objects that comprise Winawsvr.

Table 2-1 Winawsvr objects

Object Description Reference

CRemoteDataManager Provides the methods for

creating, opening, modifying,
saving, and deleting
CRemoteData objects

CRemoteData Defines the parameters for

accessing and controlling
pcAnywhere remote
functionality

CHostDataManager Provides the methods for

creating, opening, modifying,
saving, and deleting CHostData
objects

CHostData Defines the parameters for

accessing and controlling
pcAnywhere host functionality

See “CRemoteDataManager

methods” on page 20.

See “CRemoteData

properties” on page 26.

See “CRemoteDataEx

object” on page 36.

See “CHostDataManager

methods” on page 39.

See “CHostData properties”
on page 44.

See “CHostDataEx object”
on page 55.

Awrem32 has one object, which consists of eight interfaces to support remote
control and file transfer sessions.

See “Awrem32 functions” on page 63.

Some functions are no longer supported. However, object definitions are
provided for use with earlier versions of pcAnywhere.

For functions that require passwords, password values can be set but not
retrieved. This is for security purposes.

CRemoteDataManager methods

The CRemoteDataManager methods provide the parameters and return values
for accessing and controlling CRemoteData objects.

CurrentDirectory()

Returns the full path name of the current directory in which pcAnywhere
remote objects are stored.

Table 2-2 defines the CurrentDirectory() return value.

Table 2-2 CurrentDirectory() return value

Return value Description

String The full path name of the current pcAnywhere data

ChangeDirectory(NewDirectory)

Changes the current directory in which pcAnywhere remote objects are stored.

Table 2-3 defines the ChangeDirectory parameter.

Table 2-3 ChangeDirectory parameter

Parameter Description

NewDirectory Name of an existing directory

21Visual Basic object definitions

CRemoteDataManager methods

directory

Table 2-4 defines the ChangeDirectory return value.

Table 2-4 ChangeDirectory return value

Return value Description

Boolean TRUE if successful

FindFirst(Pattern, Name string)

Finds the first pcAnywhere remote object file (*.chf) in the current directory,
based on the specified file name pattern.

Table 2-5 defines the FindFirst parameters.

Table 2-5 FindFirst parameters

Parameter Description

Pattern as string File name pattern to filter object files (an asterisk [*] finds

Name as string Return buffer for the full path name of the remote object

all files in the current directory)

file that matches the specified pattern

22 Visual Basic object definitions

CRemoteDataManager methods

Table 2-6 defines the FindFirst return value.

Table 2-6 FindFirst return value

Return value Description

Boolean TRUE if a remote object file that matches the specified

FindNext(Name)

After FindFirst() has been successfully called to get the name of a remote object
file in the current directory, FindNext() can be called to find the next file that
matches the pattern, if any.

Table 2-7 defines the FindNext parameter.

Table 2-7 FindNext parameter

pattern is found. The full path name of the matching file is
stored in Name.

Parameter Description

Name as string Return buffer for the full path name of the remote object

file that matches the pattern that is specified in the
original call to FindFirst()

Table 2-8 defines the FindNext return value.

Table 2-8 FindNext return value

Return value Description

Boolean TRUE if another remote object file that matches the

pattern that is specified in the call to FindFirst() is found.
The full path name of the matching file is stored in Name.

RetrieveObject(Name, AccessMode, Password)

Retrieves a CRemoteData object by file name.

Table 2-9 defines the RetrieveObject parameters.

Table 2-9 RetrieveObject parameters

Parameter Description

Name as string The fully qualified remote object file name to be loaded.

AccessMode as integer Specifies how this object is to be used. This relates to the

password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

Password as string Object password. May be NULL.

23Visual Basic object definitions

CRemoteDataManager methods

Table 2-10 defines the RetrieveObject return value.

Table 2-10 RetrieveObject return value

Return value Description

Object CRemoteData object from the specified file

RetrieveObjectEx(Name, AccessMode, Password)

Retrieves a CRemoteDataEx object by file name.

Table 2-11 defines the RetrieveObjectEx parameters.

Table 2-11 RetrieveObjectEx parameters

Parameter Description

Name as string The fully qualified remote object file name to be loaded.

AccessMode as integer Specifies how this object is to be used. This relates to the

password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

Password as string Object password. May be NULL.

24 Visual Basic object definitions

CRemoteDataManager methods

Table 2-12 defines the RetrieveObjectEx return value.

Table 2-12 RetrieveObjectEx return value

Return value Description

Object CRemoteDataEx object from the specified file

CreateObject(Name)

Creates a CRemoteData object and returns an LPDISPATCH pointer to it.

Table 2-13 defines the CreateObject parameter.

Table 2-13 CreateObject parameter

Parameter Description

Name as string The fully qualified remote object file name for the new

object

Table 2-14 defines the CreateObject return value.

Table 2-14 CreateObject return value

Return value Description

Object CRemoteData

CreateObjectEx(Name)

Creates a CRemoteDataEx object and returns an LPDISPATCH pointer to it.

Table 2-15 defines the CreateObjectEx parameter.

Table 2-15 CreateObjectEx parameter

Parameter Description

Name as string The fully qualified remote object file name for the new

Table 2-16 defines the CreateObjectEx return value.

Table 2-16 CreateObjectEx return value

object

Return value Description

Object CRemoteDataEx

DeleteObject(Name, Password)

Deletes a remote object file.

Table 2-17 defines the DeleteObject parameters.

Table 2-17 DeleteObject parameters

Parameter Description

Name as string The fully qualified remote object file name of the object to

Password as string Object password

Table 2-18 defines the DeleteObject return value.

Table 2-18 DeleteObject return value

Return value Description

25Visual Basic object definitions

CRemoteDataManager methods

be deleted

Boolean TRUE if object is deleted

26 Visual Basic object definitions

CRemoteData properties

CRemoteData properties

Table 2-19 defines the properties and parameters that are available for the

CRemoteData object. Replace the information in angle brackets with the actual
values.

Table 2-19 CRemoteData properties and parameters

Property Parameter Description

<CRemoteData>.ComputerName(String) String Sets the computer name or IP address of the host

computer.

<CRemoteData>.PhoneNumber(String) String Sets the phone number of the host computer.

<CRemoteData>.UseDialingProperties(Bool) Bool Sets the system dialing properties.

<CRemoteData>.RedialCount(Integer) Integer Sets the number of redial attempts before

cancelling the call.

<CRemoteData>.RedialDelay(Integer) Integer Sets the number of seconds to wait between redial

attempts.

<CRemoteData>.AutoLoginName(String) String Sets the name of the user for automatic login.

For more information about using domain logins,
see “CRemoteDataEx object” on page 36.

<CRemoteData>.AutoLoginPassword(String) String Sets the password for automatic logins in the

remote object.

For security reasons, the pcAnywhere Automation
Server does not provide the ability to read the
password value. A password value is not returned.

<CRemoteData>.Password(String) String Sets the password on the remote object for use with

the ExecuteProtection, ReadProtection, and
WriteProtection settings.

For security reasons, the pcAnywhere Automation
Server does not provide the ability to read the
password value. A password value is not returned.

<CRemoteData>.ExecuteProtection(Bool) Bool Sets the requirement of a password to execute the

object. Set by Password.

<CRemoteData>.ReadProtection(Bool) Bool Sets the requirement of a password to view the

<CRemoteData>.WriteProtection(Bool) Bool Sets the requirement of a password to save changes

<CRemoteData>.LogSession(Bool) Bool Activates and deactivates session logging.

properties of the remote object. Set by Password.

to the remote object. Set by Password.

CRemoteData properties

Table 2-19 CRemoteData properties and parameters

Property Parameter Description

<CRemoteData>.RecordFile(String) String Sets the fully qualified path and name to the

location of the file that records the active session.

<CRemoteData>.RecordSession(Bool) Bool Activates and deactivates automatic session

recording.

<CRemoteData>.ReadObject(String) String Sets the password of the object. Use this property

to refresh the local data copy of the remote object.

<CRemoteData>.WriteObject(String) String Sets the password of the object. Use this property

to create the remote object or to write changes that
you have made to the remote object.

Table 2-20 defines the properties and return values for CRemoteData. Replace

the information in angle brackets with the actual values.

27Visual Basic object definitions

Table 2-20 CRemoteData properties and return values

Property Return

Description

value

String = <CRemoteData>.ComputerName String Returns the computer name or IP address of the

host computer

String = <CRemoteData>.PhoneNumber String Returns the phone number of the host computer

Bool = <CRemoteData>.UseDialingProperties Bool Returns the system dialing properties that are set

in the remote object

Integer = <CRemoteData>.RedialCount Integer Returns the number of redial attempts that is set in

the remote object

Integer = <CRemoteData>.RedialDelay Integer Returns the number of seconds between redial

attempts

String = <CRemoteData>.AutoLoginName String Returns the login name that is used for automatic

logins

Bool = <CRemoteData>.ExecuteProtection Bool Returns the value of the ExecuteProtection setting

Bool = <CRemoteData>.ReadProtection Bool Returns the value of the ReadProtection setting

Bool = <CRemoteData>.WriteProtection Bool Returns the value of the WriteProtection setting

Bool = <CRemoteData>.LogSession Bool Returns TRUE if session logging is enabled

String = <CRemoteData>.RecordFile String Returns the fully qualified path and name of the

session recording file

28 Visual Basic object definitions

CRemoteData properties

Table 2-20 CRemoteData properties and return values

Property Return

Description

value

Bool = <CRemoteData>.RecordSession Bool Returns the value of the session recording setting

Connection type properties

Table 2-21 defines the connection type properties and parameters. Replace the

information in angle brackets with the actual values.

Table 2-21 Connection type properties and parameters

Property Parameter Description

<CRemoteData>.ConnectionType(String) String Sets the connection type of the remote. The value

that is passed in must be a valid connection type as
defined by the FirstConnectionType() and
NextConnectionType() functions.

The following are examples of valid connection
types:

■ COM1

■ COM2

■ COM3

■ COM4

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ TCP/IP

■ SPX

■ NetBIOS

■ Infrared

■ ISDN via CAPI 2.0

■ Modem name (as it appears on the computer)

CRemoteData properties

Table 2-22 defines the connection type properties and return values. Replace the

information in angle brackets with the actual values.

Table 2-22 Connection type properties and return values

29Visual Basic object definitions

Property Return

Description

value

String = <CRemoteData>.ConnectionTypes String Returns the connection type of the

remote object.

Integer = <CRemoteData>.ConnectionType Integer Returns the number of available

connection types.

The following are examples of valid
connection types:

■ COM1

■ COM2

■ COM3

■ COM4

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ TCP/IP

■ SPX

■ NetBIOS

■ Infrared

■ ISDN via CAPI 2.0

■ Modem name (as it appears on the

computer)

String = <CRemoteData>.FirstConnectionType String Returns the first available connection

String = <CRemoteData>.NextConnectionType String Returns the next available connection

Bool =
<CRemoteData>.FindConnectionType(ConnectionType)

type.

type. This is called sequentially for the
number of connection types that is set
in <CRemoteData>.ConnectionType to
enumerate all connection types.

Bool Returns TRUE if the named connection

type is found in the list of available
connection types.

30 Visual Basic object definitions

CRemoteData properties

Dialing properties

Table 2-23 defines the properties and parameters for setting the dialing

properties for modem connections. Replace the information in angle brackets
with the actual values.

Table 2-23 Properties and parameters for dialing properties

Property Parameter Description

<CRemoteData>.AreaCode(String) String Sets the area code dialing properties for modem

connections

<CRemoteData>.CountryCode(String) String Sets the country code dialing properties for

modem connections

Table 2-24 defines the properties and return values for modem dialing

properties. Replace the information in angle brackets with the actual values.

Table 2-24 Properties and return values for dialing properties

Property Return

Description

value

String = <CRemoteData>.AreaCode String Returns the area code dialing properties.

String = <CRemoteData>.CountryCode String Returns the dialing properties country code.

Integer = <CRemoteData>.CountryCodes Integer Returns the number of available country codes.

String = <CRemoteData>.FirstCountryCode String Returns the first available country code that is

listed in the operating system.

String = <CRemoteData>.NextCountryCode String Returns the next available country code. This is

called sequentially for the number of country
codes that is set in <CRemoteData.CountryCodes>
to enumerate all country codes.

CRemoteData properties

COM device properties

Table 2-25 describes the properties and parameters that let you customize the

port settings for modem and other COM-based connections. Replace the
information in angle brackets with the actual values.

Table 2-25 COM device properties and parameters

Property Parameter Description

<CRemoteData>.ComParity(String) String Sets the communications parity

The following values are valid:

■ <None>

■ Odd

■ Even

■ Mark

■ Space

31Visual Basic object definitions

<CRemoteData>.ComFlowControl(String) String Sets the flow control of COM-based connection

types

The following values are valid:

■ <None>

■ XONXOFF

■ RTS/CTS

■ Both

<CRemoteData>.ComStartedBy(String) String Sets the start setting of COM-based connection

types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>’s

■ Modem response

32 Visual Basic object definitions

CRemoteData properties

Table 2-25 COM device properties and parameters

Property Parameter Description

<CRemoteData>.ComEndedBy(String) String Sets the end setting of COM-based connection

types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

<CRemoteData>.ComSpeed(Long) Long Contains the maximum COM speed setting

The following values are valid:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

■ 9600

■ 38400

■ 57600

■ 115200

Table 2-26 describes the COM device properties and return values. Replace the

information in angle brackets with the actual values.

Table 2-26 COM device properties and return values

Property Return

Description

value

String = <CRemoteData>.ComParity String Returns one of the following values for

communications parity:

■ <None>

■ Odd

■ Even

■ Mark

■ Space

Table 2-26 COM device properties and return values

33Visual Basic object definitions

CRemoteData properties

Property Return

Description

value

String = <CRemoteData>.ComFlowControl String Returns the Com Flow setting of the remote object

The following values are valid:

■ <None>

■ XONXOFF

■ RTS/CTS

■ Both

String = <CRemoteData>.ComStartedBy String Returns the Com Start control of COM-based

connection types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>’s

■ Modem response

String = <CRemoteData>.ComEndedBy String Returns the Com End control of COM-based

connection types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

34 Visual Basic object definitions

CRemoteData properties

Table 2-26 COM device properties and return values

Property Return

Description

value

Long = <CRemoteData>.ComSpeed Long Returns the current setting of the Com Speed of

the remote object

The following values are valid:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

■ 9600

■ 38400

■ 57600

■ 115200

NetBIOS device properties

Table 2-27 defines the property and parameter for a NetBIOS network device.

Replace the information in angle brackets with the actual values.

Table 2-27 NetBIOS property and parameter

Property Parameter Description

<CRemoteData>.LanaNumber(Integer) Integer Sets the LAN Adapter (LANA) number for NetBIOS

connections

Table 2-28 defines the NetBIOS property and return value. Replace the

information in angle brackets with the actual values.

Table 2-28 NetBIOS property and return value

Property Return

Description

value

Integer = <CRemoteData>.LanaNumber Integer Returns the current setting of the LAN Adapter

(LANA) number for NetBIOS connections

CRemoteData properties

ISDN via CAPI 2.0 device properties

Table 2-29 defines the properties and parameters for European ISDN

connections. Replace the information in angle brackets with the actual values.

Table 2-29 ISDN via CAPI 2.0 properties and parameters

Property Parameter Description

<CRemoteData>.CapiChannelBonding(Bool) Bool Activates or deactivates channel bonding for ISDN

CAPI devices

<CRemoteData>.CapiExtensions(String) String Sets any additional CAPI extensions that are

needed for communications

Table 2-30 defines the properties and return values for European ISDN

connections. Replace the information in angle brackets with the actual values.

Table 2-30 ISDN via CAPI 2.0 properties and return values

35Visual Basic object definitions

Property Return

Description

value

Bool= <CRemoteData>.CapiChannelBonding Bool Returns the current ISDN CAPI channel bonding

setting in the remote object

String = <CRemoteData>.CapiExtensions String Returns the current list of CAPI extensions from

the remote object

36 Visual Basic object definitions

CRemoteDataEx object

CRemoteDataEx object

The CRemoteDataEx object contains the same functionality as the CRemoteData
object with some additional functionality.

Table 2-31 describes the properties and parameters. Replace the information in

angle brackets with the actual values.

Table 2-31 CRemoteDataEx parameters

Property Parameter Description

<CRemoteData>.PrivateKey(String) String Sets the name of the private key container to use.

<CRemoteData>.CertificateName(String) String Sets the common name of the private key to use.

<CRemoteData>.EncryptionLevel(Byte) Byte Sets the encryption level.

The following values are valid:

■ -1: None

■ 0: pcAnywhere

■ 1: Symmetric

■ 2: Public key

<CRemoteData>.DenyLowerEncrypt(Bool) Bool Defines whether the remote computer allows a

connection to a host computer that uses a lower
level of encryption.

<CRemoteData>.AutoDomain(String) String Sets the domain name for automatic logins. This

option is used with NT authentication and
Windows authentication.

Table 2-32 describes the properties and return values for the CRemoteDataEx

object. Replace the information in angle brackets with the actual values.

Table 2-32 CRemoteDataEx properties and return values

Property Return

Description

value

String = <CRemoteData>.PrivateKey String Returns the name of the currently active private

key container.

String = <CRemoteData>.CertificateName String Returns the common name of the active private

key container.

Table 2-32 CRemoteDataEx properties and return values

37Visual Basic object definitions

CRemoteDataEx object

Property Return

Description

value

Byte = <CRemoteData>.EncryptionLevel Byte Returns one of the following encryption settings:

■ -1: None

■ 0: pcAnywhere

■ 1: Symmetric

■ 2: Public key

Bool = <CRemoteData>.DenyLowerEncrypt Bool Returns the value of the deny lower encryption

setting.

String = <CRemoteData>.AutoDomain String Returns the domain name setting for automatic

logins. This option is used with NT authentication
and Windows authentication.

Visual Basic sample code for remote functionality

The following Visual Basic sample code retrieves a remote data object and
modifies its properties:

Private Sub Command1_Click()
Dim RemoteDataManager as Object
Dim RemoteData as Object
Dim s as string

'Create CRemoteDataManager object
Set RemoteDataManager = CreateObject(WINAWSVR.REMOTEDATAMANAGER)

'display and change current directory
s = RemoteDataManager.CurrentDirectory()
MsgBox ( s )
RemoteDataManager.ChangeDirectory ("C:\dev\bin.w32\data")
s = RemoteDataManager.CurrentDirectory()
MsgBox ( s )

'retrieve remote data object
Set RemoteData = RemoteDataManager.RetrieveObjectEx("pod.CHF",
2, 0)

'display some properties
s = RemoteData.AreaCode()

38 Visual Basic object definitions

CRemoteDataEx object

Use the FindFirst and FindNext methods to display the remote file in a directory
as follows:

MsgBox (s)
s = RemoteData.PhoneNumber()
MsgBox (s)

'set some properties
RemoteData.AreaCode = "212"
RemoteData.PhoneNumber = "555-5555"

'write object to disk
RemoteData.WriteObject (0)
End Sub

Private Sub Command5_Click()

Dim RemoteDataManager as Object
Dim RemoteData as Object
Dim s as string

Set RemoteDataManager =
CreateObject("WINAWSVR.REMOTEDATAMANAGER")
RemoteDataManager.ChangeDirectory
("C:\dev\bin.w32\data")
RemoteDataManager.FindFirst "*", s
MsgBox (s)
RemoteDataManager.FindNext s
MsgBox (s)

End Sub

Create a remote object. Set the connection type to TCP/IP and the computer
name “Host1,” and then launch it as follows:

Private Sub Command6_Click()
Dim RemoteDataManager as Object
Dim RemoteData as Object
Dim s as string

Set RemoteDataManager =
CreateObject("WINAWSVR.REMOTEDATAMANAGER")
MsgBox (RemoteDataManager.CurrentDirectory())

RemoteDataManager.ChangeDirectory ("C:\dev\bin.w32\data")
MsgBox (RemoteDataManager.CurrentDirectory())
Set RemoteData = RemoteDataManager.CreateObject("test")
RemoteData.ConnectionType = "TCP/IP"
RemoteData.ComputerName = "Host1"
s = RemoteData.ConnectionType
MsgBox (s)
s = RemoteData.ComputerName
MsgBox (s)
RemoteData.WriteObject (0)
End Sub

CHostDataManager methods

39Visual Basic object definitions

CHostDataManager methods

The CHostDataManager methods provide the parameters and return values for
accessing and controlling CHostData objects.

CurrentDirectory()

Returns the full path name of the current directory in which pcAnywhere host
objects are stored.

Table 2-33 defines the return value for CurrentDirectory.

Table 2-33 CurrentDirectory() return value

Return value Description

String The full path name of the current pcAnywhere data

FindFirst(Pattern, Name string)

Finds the first pcAnywhere host object file (*.bhf) in the current directory, based
on the specified file name pattern.

Table 2-34 defines the parameters for FindFirst.

directory

Table 2-34 FindFirst parameters

Parameter Description

Pattern as string File name pattern to filter object files (an asterisk [*] finds

all files in the current directory)

40 Visual Basic object definitions

CHostDataManager methods

Table 2-34 FindFirst parameters

Parameter Description

Name as string Return buffer for the full path name of the host object file

Table 2-35 defines the return value for FindFirst.

Table 2-35 FindFirst return value

Return value Description

Boolean TRUE if a host object file matching the specified pattern is

FindNext(Name)

that matches the specified pattern

found. The full path name of the matching file is stored in
Name.

After FindFirst() has been successfully called to get the name of a host object file
in the current directory, FindNext() can be called to find the next file that
matches the pattern, if any.

Table 2-36 defines the parameter for FindNext.

Table 2-36 FindNext parameter

Parameter Description

Name as string Return buffer for the full path name of the host object file

that matches the pattern specified in the original call to
FindFirst()

Table 2-37 defines the return value for FindNext.

Table 2-37 FindNext return value

Return value Description

Boolean TRUE if another host object file matching the pattern

specified in the call to FindFirst() is found. The full path
name of the matching file is stored in Name.

RetrieveObject(Name, AccessMode, Password)

Retrieves a CHostData object by file name.

Table 2-38 defines the parameters for RetrieveObject.

Table 2-38 RetrieveObject parameters

Parameter Description

Name as string The fully qualified host object file name to be loaded.

AccessMode as integer Specifies how this object is to be used. This relates to the

password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

Password as string Object password. May be NULL.

41Visual Basic object definitions

CHostDataManager methods

Table 2-39 defines the return value for RetrieveObject.

Table 2-39 RetrieveObject return value

Return value Description

Object CHostData object from the specified file

RetrieveObjectEx(Name, AccessMode, Password)

Retrieves a CHostDataEx object by file name.

Table 2-40 defines the parameters for RetrieveObjectEx.

Table 2-40 RetrieveObjectEx parameters

Parameter Description

Name as string The fully qualified host object file name to be loaded.

AccessMode as integer Specifies how this object is to be used. This relates to the

password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

Password as string Object password. May be NULL.

42 Visual Basic object definitions

CHostDataManager methods

Table 2-41 defines the return value for RetrieveObjectEx.

Table 2-41 RetrieveObjectEx return value

Return value Description

Object CHostDataEx object from the specified file

CreateObject(Name)

Creates a CHostData object and returns an LPDISPATCH pointer to it.

Table 2-42 defines the parameter for CreateObject.

Table 2-42 CreateObject parameter

Parameter Description

Name as string The fully qualified host object file name for the new object

Table 2-43 defines the return value for CreateObject.

Table 2-43 CreateObject return value

Return value Description

Object CHostData

CreateObjectEx(Name)

Creates a CHostDataEx object and returns an LPDISPATCH pointer to it.

Table 2-44 defines the parameter for CreateObjectEx.

Table 2-44 CreateObjectEx parameter

Parameter Description

Name as string The fully qualified host object file name for the new object

Table 2-45 defines the return value for CreateObjectEx.

Table 2-45 CreateObjectEx return value

Return value Description

Object CHostDataEx

DeleteObject(Name, Password)

Deletes a host object file.

Table 2-46 defines the parameters for DeleteObject.

Table 2-46 DeleteObject parameters

Parameter Description

Name as string The fully qualified host object file name of the object to be

Password as string Object password

Table 2-47 defines the return value for DeleteObject.

Table 2-47 DeleteObject return value

Return value Description

43Visual Basic object definitions

CHostDataManager methods

deleted

Launch(Name)

Boolean TRUE if object is deleted

Launches a host object file, which opens the pcAnywhere host terminal window.

Table 2-48 defines the parameter for launch.

Table 2-48 Launch parameter

Parameter Description

Name as string The fully qualified host object file of the object to be

launched

Table 2-49 defines the Launch return value.

Table 2-49 Launch return value

Return value Description

Boolean TRUE if object is successfully launched

44 Visual Basic object definitions

CHostData properties

CHostData properties

Table 2-50 describes the properties and parameters that are available for the

CHostData object. Replace the information in angle brackets with the actual
values.

Table 2-50 CHostData properties and parameters

Property Parameter Description

<CHostData>.PhoneNumber(String) String Sets the phone number of the host computer.

<CHostData>.UseDialingProperties(Bool) Bool Sets the system dialing properties.

<CHostData>.RedialCount(Integer) Integer Sets the number of redial attempts before

cancelling the call.

<CHostData>.RedialDelay(Integer) Integer Sets the number of seconds to wait between redial

attempts.

<CHostData>.Password(String) String Sets the password on the host object for use with

the ExecuteProtection, ReadProtection, and
WriteProtection settings.

For security reasons, the pcAnywhere Automation
Server does not provide the ability to read the
password value. A password value is not returned.

<CHostData>.ExecuteProtection(Bool) Bool Sets the requirement of a password to execute the

object. Set by Password.

<CHostData>.ReadProtection(Bool) Bool Sets the requirement of a password to view the

properties of the host object. Set by Password.

<CHostData>.WriteProtection(Bool) Bool Sets the requirement of a password to save

changes to the host object. Set by Password.

<CHostData>.LogSession(Bool) Bool Activates and deactivates session logging.

<CHostData>.RecordFile(String) String Sets the fully qualified path and name to the

location of the file that records the active session.

<CHostData>.RecordSession(Bool) Bool Activates and deactivates automatic session

recording.

<CHostData>.ReadObject(String) String Sets the password for the object. You can use this

<CHostData>.WriteObject(String) String Sets the password for the object. Use this property

property to refresh the local data copy of the host
object.

to create the host object or to write changes that
you have made to the host object.

CHostData properties

Table 2-51 describes the CHostData properties and return values. Replace the

information in angle brackets with the actual values.

Table 2-51 CHostData properties and return values

45Visual Basic object definitions

Property Return

Description

value

String = <CHostData>.PhoneNumber String Returns the phone number of the host computer

Bool = <CHostData>.UseDialingProperties Bool Returns the use of the system dialing properties

that are set in the host object

Integer = <CHostData>.RedialCount Integer Returns the number of redial attempts that is set

in the host object

Integer = <CHostData>.RedialDelay Integer Returns the number of seconds between redial

attempts

Bool = <CHostData>.ExecuteProtection Bool Returns the value of the ExecuteProtection setting

Bool = <CHostData>.ReadProtection Bool Returns the value of the ReadProtection setting

Bool = <CHostData>.WriteProtection Bool Returns the value of the Write Protection setting

Bool = <CHostData>.LogSession Bool Returns TRUE if session logging is enabled

String = <CHostData>.RecordFile String Returns the fully qualified path and name of the

session recording file

Bool = <CHostData>.RecordSession Bool Returns the value of the session recording setting

46 Visual Basic object definitions

CHostData properties

Connection type properties

Table 2-52 describes the connection type properties and parameters. Replace

the information in angle brackets with the actual values.

Table 2-52 Connection type properties and parameters

Property Parameter Description

<CHostData>.ConnectionType(String) String Sets the connection type of the host. The value

that is passed in must be a valid connection type
as defined by the FirstConnectionType() and
NextConnectionType() functions.

The following are examples of valid connection
types:

■ COM1

■ COM2

■ COM3

■ COM4

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ TCP/IP

■ SPX

■ NetBIOS

■ Infrared

■ ISDN via CAPI 2.0

■ Modem name (as it appears on the computer)

<CHostData>.AssignConnection(String) String Sets the connection type that is defined in the

<CHostData>.UnassignConnection(String) String Sets the connection type that is defined in the

string to active status.

string to inactive status.

CHostData properties

Table 2-53 describes the connection type properties and return values. Replace

the information in angle brackets with the actual values.

Table 2-53 Connection type properties and return values

47Visual Basic object definitions

Property Return

Description

value

String = <CHostData>.ConnectionTypes String Returns the connection type of the host object.

Integer = <CHostData>.ConnectionType Integer Returns the number of available connection types.

The following are examples of valid connection
types:

■ COM1

■ COM2

■ COM3

■ COM4

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ TCP/IP

■ SPX

■ NetBIOS

■ Infrared

■ ISDN via CAPI 2.0

■ Modem name (as it appears on the computer)

String = <CHostData>.FirstConnectionType String Returns the first available connection type.

String = <CHostData>.NextConnectionType String Returns the next available connection type. This is

called sequentially for the number of connection
types that is set in <CHostData>.ConnectionTypes
to enumerate all connection types.

Bool = <CHostData>.FindConnectionType
(ConnectionType)

Integer =
<CHostData>.MaxAssignedConnections

Bool Returns TRUE if the named connection type is

found in the list of available connection types.

Integer Returns the maximum number of connection

types that can be active on this host.

String = <CHostData>.FirstAssignedConnection String Returns the first assigned active connection type.

String = <CHostData>.NextAssignedConnection String Returns the next assigned active connection type.

Bool = <CHostData>.FindAssignedConnection
(ConnectionType)

Bool Returns TRUE if the connection type that is

passed in matches any of the active connection
types.

48 Visual Basic object definitions

CHostData properties

AssignConnection(ConnectionType) method

The AssignConnection(Connection Type) method places the requested
connection type on the host object’s list of assigned connection types and makes
it the current connection type when processing subsequent device-specific
method calls.

If the requested connection type is already on the list of assigned connections,
the list of assigned connections does not change. Only the current connection
type is changed to the requested type. It is normal to call the AssignConnection
method on the same object multiple times in the course of getting and setting
connection-specific values.

AssignConnection returns TRUE if the connection type that is passed in exists
on the computer and is either successfully assigned or already assigned. It
returns FALSE if either the requested connection type does not exist on the
computer or the current assigned connection count is already at the maximum
allowed level.

A pcAnywhere host object can support up to two assigned connection types. The
AssignConnection method returns FALSE if it detects an attempt to exceed this
limit.

Table 2-54 defines the AssignConnection parameter.

Table 2-54 AssignConnection parameter

Parameter Description

ConnectionType as string The name of a connection device type to be assigned

Table 2-55 defines the AssignConnection return value.

Table 2-55 AssignConnection return value

Return value Description

Boolean TRUE if this device type is available and the maximum

allowed assigned connection count has not already been
reached

UnassignConnection(ConnectionType) method

The UnassignConnection(Connection Type) method returns TRUE if the
connection type that is passed in is successfully removed from the list of
assigned connection types.

Table 2-56 defines the UnassignConnection parameter.

Table 2-56 UnassignConnection parameter

Parameter Description

ConnectionType as string The name of a connection device type to be unassigned

Table 2-57 defines the UnassignConnection return value.

Table 2-57 UnassignConnection return value

Return value Description

Boolean TRUE if this device type is successfully unassigned

Dialing properties

Table 2-58 defines the properties and return values for setting the dialing

properties for modem connections. Replace the information in angle brackets
with the actual values.

49Visual Basic object definitions

CHostData properties

Table 2-58 Properties and parameters for modem dialing properties

Property Parameter Description

<CHostData>.AreaCode(String) String Sets the area code for the modem connections

<CHostData>.CountryCode(String) String Sets the country code for modem connections

Table 2-59 defines the properties and return values for modem dialing

properties. Replace the information in angle brackets with the actual values.

Table 2-59 Properties and return values for modem dialing properties

Property Return

Description

value

String = <CHostData>.AreaCode String Returns the area code.

String = <CHostData>.CountryCode String Returns the country code.

Integer = <CHostData>.CountryCodes Integer Returns the number of available country codes.

String= <CHostData>.FirstCountryCode String Returns the first available country code that is

listed in the operating system.

50 Visual Basic object definitions

CHostData properties

Table 2-59 Properties and return values for modem dialing properties

Property Return

Description

value

String = <CHostData>.NextCountryCode String Returns the next available country code. This is

called sequentially for the number of country
codes that is set in <CHostData>.CountryCodes to
enumerate all country codes.

COM device properties

Table 2-60 defines the properties and parameters that let you customize the

port settings for modem and other COM-based connections. Replace the
information in angle brackets with the actual values.

Table 2-60 COM device properties and parameters

Property Parameter Description

<CHostData>.ComParity(String) String Sets the communications parity

The following values are valid:

■ <None>

■ Odd

■ Even

■ Mark

■ Space

<CHostData>.ComFlowControl(String) String Sets the flow control of COM-based connection

types

The following values are valid:

■ <None>

■ XONXOFF

■ RTS/CTS

■ Both

CHostData properties

Table 2-60 COM device properties and parameters

Property Parameter Description

<CHostData>.ComStartedBy(String) String Sets the start setting of COM-based connection

types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>’s

■ Modem response

<CHostData>.ComEndedBy(String) String Sets the end setting of COM-based connection

types

51Visual Basic object definitions

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

<CHostData>.ComSpeed(Long) Long Sets the maximum COM speed setting

The following values are valid:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

■ 9600

■ 38400

■ 57600

■ 115200

52 Visual Basic object definitions

CHostData properties

Table 2-61 describes the COM device properties and return values. Replace the

information in angle brackets with the actual values.

Table 2-61 COM device properties and return values

Property Return

Description

value

String = <CHostData>.ComParity String Returns one of the following values as the

communications parity:

■ <None>

■ Odd

■ Even

■ Mark

■ Space

String = <CHostData>.ComFlowControl String Returns the Com Flow setting of the host object

The following values are valid:

■ <None>

■ XONXOFF

■ RTS/CTS

■ Both

String = <CHostData>.ComStartedBy String Returns the Com Start control of COM-based

connection types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>’s

■ Modem response

String = <CHostData>.ComEndedBy String Returns the Com End control of COM-based

connection types

The following values are valid:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

Table 2-61 COM device properties and return values

53Visual Basic object definitions

CHostData properties

Property Return

Description

value

Long = <CHostData>.ComSpeed Long Returns the current setting of the Com Speed of

the host object

The following values are valid:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

■ 9600

■ 38400

■ 57600

■ 115200

NetBIOS device properties

Table 2-62 defines the property and parameter for NetBIOS network devices.

Replace the information in angle brackets with the actual values.

Table 2-62 NetBIOS property and parameter

Property Parameter Description

<CHostData>.LanaNumber(Integer) Integer Sets the LAN Adapter (LANA) number for NetBIOS

connections

Table 2-63 defines the property and return value for NetBIOS network devices.

Replace the information in angle brackets with the actual values.

Table 2-63 NetBIOS return values

Property Return

Description

value

Integer = <CHostData>.LanaNumber Integer Returns the current setting of the LAN Adapter

(LANA) number for NetBIOS connections

54 Visual Basic object definitions

CHostData properties

ISDN via CAPI 2.0 device properties

Table 2-64 defines the properties and parameters for European ISDN

connections. Replace the information in angle brackets with the actual values.

Table 2-64 ISDN via CAPI 2.0 properties and parameters

Property Parameter Description

<CHostData>.CapiChannelBonding(Bool) Bool Activates or deactivates channel bonding for ISDN

CAPI devices

<CHostData>.CapiExtensions(String) String Sets any additional CAPI extensions that are

needed for communications

Table 2-65 defines the properties and return values for European ISDN

connections.

Table 2-65 ISDN via CAPI 2.0 properties and return values

Property Return

Description

value

Bool= <CHostData>.CapiChannelBonding Bool Returns the current ISDN CAPI channel bonding

setting in the host object

String = <CHostData>.CapiExtensions String Returns the current list of CAPI extensions from

the host object

CHostDataEx object

CHostDataEx object

The CHostDataEx object contains the same functionality as the CHostData
object with some additional functionality.

Table 2-66 describes the properties and parameters. Replace the information in

angle brackets with the actual values.

Table 2-66 CHostDataEx properties and parameters

Property Parameter Description

<CHostData>.CryptPrivateKey(String) String Sets the name of the private key container to use.

<CHostData>.CryptCommonName(String) String Sets the common name of the private key to use.

<CHostData>.CryptReqLevel(Byte) Byte Sets the encryption level.

The following values are valid:

■ -1: None

■ 0: pcAnywhere

■ 1: Symmetric

■ 2: Public key

55Visual Basic object definitions

<CHostData>.CryptRefuseLower(Bool) Bool Defines whether the host computer accepts

connections from a remote computer that uses a
lower level of encryption.

<CHostData>.CallersPath(String) String Sets the fully qualified path to the caller files.

<CHostData>.ConfirmConnect(Bool) Bool Defines whether the host user will be prompted

to confirm connections.

<CHostData>.ConfirmTimeout(Byte) Byte Sets the number of seconds before the prompt to

confirm the connection time limit expires.

<CHostData>.ConfirmDeny(Bool) Bool Defines whether the connection should be ended

if the prompt to confirm the connection time
limit expires.

<CHostData>.PwCaseSensitive(Bool) Bool Forces the use of case-sensitive passwords.

<CHostData>.PwAttempts(Byte) Byte Sets the number of consecutive failed logon

attempts that are allowed before ending the
connection.

<CHostData>.PwTimeout(Byte) Byte Sets the number of minutes that a user has to

complete the logon before the connection is
dropped.

56 Visual Basic object definitions

CHostDataEx object

Table 2-66 CHostDataEx properties and parameters

Property Parameter Description

<CHostData>.ActiveKbds(Byte) Byte Defines which mouse and keyboard will be active

during the connection.

The following values are valid:

■ 0: Host and remote

■ 1: Host

■ 2: Remote

<CHostData>.InactiveTimeout(Byte) Byte Sets the number of minutes in which the

keyboard and mouse can be inactive before the
connection is ended.

<CHostData>.LockSystemWhileWait(Bool) Bool Sets the lock host computer upon startup setting.

<CHostData>.MinimizeOnLaunch(Bool) Bool Sets the run minimized host startup option.

<CHostData>.RunAsService(Bool) Bool Enables the host to run as a service.

<CHostData>.ConnLostWait(Byte) Byte Sets the number of minutes to wait before

allowing another caller to connect.

<CHostData>.ConnLostHostOpts(Bool) Bool Defines whether to wait for another connection

or cancel the host if the session ends abnormally.

The following values are valid:

■ FALSE: Wait

■ TRUE: Cancel host

<CHostData>.EnableConnLostSecurity(Bool) Bool Activates or deactivates the end of session

security options for sessions that end
abnormally.

Table 2-66 CHostDataEx properties and parameters

Property Parameter Description

<CHostData>.AuthenticationType(Byte) Byte Sets the authentication type.

The following values are valid:

■ 0: pcAnywhere

■ 1: pcAnywhere

■ 2: Windows

■ 3: NT

■ 4: pcAnywhere

■ 5: pcAnywhere

■ 6: ADS Active Directory Services

■ 7: Microsoft LDAP

■ 8: FTP

■ 9: HTTP

■ 10: HTTPS

■ 11: Netscape LDAP

■ 12: Novell LDAP

■ 13: RSA SecurID

57Visual Basic object definitions

CHostDataEx object

pcAnywhere authentication is used by default if
no authentication value is set or if the set value
is not valid (for example, the authentication type
is not available).

<CHostData>.ConnLostSecurity(Byte) Byte Sets the security options for handling an

abnormal end of session.

The following values are valid:

■ 1: Log off user

■ 2: Restart host computer

■ 3: Lock computer

<CHostData>.CallbkDelay(Byte) Byte Sets the number of seconds to wait before the

host modem calls back the remote.

<CHostData>.EndSessHostOpts(Bool) Bool Defines whether the host waits for another

connection or is cancelled after a normal end of
session.

The following values are valid:

■ FALSE: Wait for next connection

■ TRUE: Cancel host

<CHostData>.EnableEndSessSecurity(Bool) Bool Activates or deactivates the security options for a

normal end of session.

58 Visual Basic object definitions

CHostDataEx object

Table 2-66 CHostDataEx properties and parameters

Property Parameter Description

<CHostData>.EndSessSecurity(Byte) Byte Sets the security options for a normal end of

session.

The following values are valid:

■ 1: Log off user

■ 2: Restart host computer

■ 3: Lock computer

<CHostData>.BlankHost(Bool) Bool Sets screen blanking on the host computer. Some

video cards do not support this option.

<CHostData>.AllowRemoteMouse(Bool) Bool Disables the use of the mouse on the remote

computer during a session.

<CHostData>.RebootOnDisconnect(Bool) Bool Forces the computer to restart after any end of

session if TRUE.

<CHostData>.PasswordAfterDisc(Bool) Bool Logs off the user after the session ends.

<CHostData>.LogFailures(Bool) Bool Logs failed password attempts.

<CHostData>.AllowDriveSecurity(Bool) Bool Enables drive security options. This setting is

valid only on NTFS file systems.

<CHostData>.UseDirectoryServices(Bool) Bool Enables the use of directory services for

authentication.

<CHostData>.DirectoryServiceEntry(String) String Sets the directory services settings.

Table 2-67 describes the properties and return values for the CHostDataEx

object. Replace the information in angle brackets with the actual values.

Table 2-67 CHostDataEx properties and return values

Property Return

Description

value

String = <CHostDataEx>.CryptPrivateKey String Returns the currently active private key

container.

String = <CHostDataEx>.CryptCommonName String Returns the common name of the active private

key container.

Table 2-67 CHostDataEx properties and return values

59Visual Basic object definitions

CHostDataEx object

Property Return

Description

value

Byte = <CHostDataEx>.CryptReqLevel Byte Returns one of the following encryption

settings:

■ -1: None

■ 0: pcAnywhere

■ 1: Symmetric

■ 2: Public key

Bool = <CHostDataEx>.CryptRefuseLower Bool Returns the value of the deny lower encryption

setting.

String = <CHostDataEx>.CallersPath String Returns the currently active path to the caller

files.

Bool = <CHostDataEx>.ConfirmConnect Bool Returns the value of the confirm connection

setting.

Byte = <CHostDataEx>.ConfirmTimeout Byte Returns the value of the deny lower encryption

setting.

Bool = <CHostDataEx>.ConfirmDeny Bool Returns the value of the disconnect if timeout

setting.

Bool = <CHostDataEx>.PwCaseSensitive Bool Returns the value of the make passwords case

sensitive setting.

Byte = <CHostDataEx>.PwAttempts Byte Returns the value of the limit login attempts per

call setting.

Byte = <CHostDataEx>.PwTimeout Byte Returns the value of the limit time to complete

login setting (in minutes).

Byte = <CHostDataEx>.ActiveKbds Byte Returns the active keyboard and mouse settings.

The following values are valid:

■ 0: Host and remote

■ 1: Host

■ 2: Remote

Byte = <CHostDataEx>. InactiveTimeout Byte Returns the number of minutes to wait before

disconnecting if the inactivity time limit expires.

Bool = <CHostDataEx>.LockSystemWhileWait Bool Returns the lock host computer upon startup

setting.

Bool = <CHostDataEx>.MinimizeOnLaunch Bool Returns the run minimized on host startup

setting.

60 Visual Basic object definitions

CHostDataEx object

Table 2-67 CHostDataEx properties and return values

Property Return

Description

value

Bool = <CHostDataEx>.RunAsService Bool Returns the run host as a service setting.

Byte = <CHostDataEx>.ConnLostWait Byte Returns the number of minutes to wait before

allowing another connection.

Bool = <CHostDataEx>.ConnLostHostOpts Bool Returns whether to wait for another connection

or cancel the host if the session ends
abnormally.

The following values are valid:

■ FALSE: Wait

■ TRUE: Cancel host

Bool = <CHostDataEx>.ConnLostWait Bool Returns the value of the security option that is

set for handling an abnormal end of session.

Byte = <CHostDataEx>.AuthenticationType Byte Returns the number reference of the

authentication type.

The following values are valid:

■ 0: pcAnywhere

■ 1: pcAnywhere

■ 2: Windows

■ 3: NT

■ 4: pcAnywhere

■ 5: pcAnywhere

■ 6: ADS Active Directory Services

■ 7: Microsoft LDAP

■ 8: FTP

■ 9: HTTP

■ 10: HTTPS

■ 11: Netscape LDAP

■ 12: Novell LDAP

■ 13: RSA SecurID

pcAnywhere authentication is used by default if
no authentication value is set or if the set value
is not valid (for example, the authentication type
is not available).

Table 2-67 CHostDataEx properties and return values

61Visual Basic object definitions

CHostDataEx object

Property Return

Description

value

Byte = <CHostDataEx>.ConnLostSecurity Byte Returns the numeric representation of the

security level that is set for handling an
abnormal end of session.

The following values are valid:

■ 1: Log off user

■ 2: Restart host computer

■ 3: Lock computer

Byte = <CHostDataEx>.CallbkDelay Byte Returns the number of seconds to wait before

the host modem calls back the remote.

Bool = <CHostDataEx>.EndSessHostOpts Bool Returns whether the host waits for another

connection or is cancelled after a normal end of
session.

The following values are valid:

■ FALSE: Wait for next connection

■ TRUE: Cancel host

Bool = <CHostDataEx>.EnableEndSessSecurity Bool Returns whether the end of session security

options are enabled for a normal end of session.

Byte = <CHostDataEx>.EndSessSecurity Byte Returns the security option that is set for a

normal end of session.

The following values are valid:

■ 1: Log off user

■ 2: Restart host computer

■ 3: Lock computer

Bool = <CHostDataEx>.BlankHost Bool Returns the screen blanking option that is set.

Bool = <CHostDataEx>.AllowRemoteMouse Bool Returns whether the remote user has keyboard

and mouse control during a session.

Bool = <CHostDataEx>.RebootOnDisconnect Bool Returns whether the host computer is restarted

after the session ends.

Bool = <CHostDataEx>.PasswordAfterDisc Bool Returns whether the host user is logged off after

the session ends.

Bool = <CHostDataEx>.LogFailures Bool Returns whether the log password failures

option is set.

62 Visual Basic object definitions

CHostDataEx object

Table 2-67 CHostDataEx properties and return values

Property Return

Description

value

Bool = <CHostDataEx>.AllowDriveSecurity Bool Returns whether the drive security option is

enabled.

Bool = <CHostDataEx>.UseDirectoryServices Bool Returns whether the directory services option is

enabled.

String = <CHostDataEx>.DirectoryServiceEntry String Returns the directory service settings.

Visual Basic sample code for host functionality

The following Visual Basic sample code retrieves a host data object and modifies
its properties:

Private Sub Command1_Click()
Dim HostDataManager as Object
Dim HostData as Object
Dim s as string

'Create CHostDataManager object
Set HostDataManager = CreateObject(WINAWSVR.BEHOSTDATAMANAGER)

'display and change current directory
s = HostDataManager.CurrentDirectory()
MsgBox ( s )
HostDataManager.ChangeDirectory ("C:\dev\bin.w32\data")
s = HostDataManager.CurrentDirectory()
MsgBox ( s )

'retrieve remote data object
Set HostData = HostDataManager.RetrieveObject("pod.BHF", 2, 0)

'display some properties
s = HostData.AreaCode()
MsgBox (s)
s = HostData.PhoneNumber()
MsgBox (s)
'set some properties
RemoteData. HostData = "212"

Awrem32 functions

RemoteData. HostData = "555-5555"

'write object to disk
HostData.WriteObject (0)
End Sub

Use the FindFirst and FindNext methods to display the host file in a directory as
follows:

Private Sub Command5_Click()

Dim HostDataManager as Object
Dim HostData as Object
Dim s as string

Set HostDataManager = CreateObject("WINAWSVR.BEHOSTDATAMANAGER")
HostDataManager.ChangeDirectory ("C:\dev\bin.w32\data")
HostDataManager.FindFirst "*", s
MsgBox (s)
HostDataManager.FindNext s
MsgBox (s)

63Visual Basic object definitions

End Sub

Awrem32 functions

The Awrem32 functions provide the parameters and return values for handling
connections between the host and remote computers.

awConnect(FileName)

Creates the connection to the host computer.

Table 2-68 defines the awConnect parameter.

Table 2-68 awConnect parameter

Parameter Description

Name as string The fully qualified .chf file name that contains information

about the host computer

64 Visual Basic object definitions

Awrem32 functions

Table 2-69 defines the awConnect return value.

Table 2-69 awConnect return value

Return value Description

Boolean TRUE if command executed

awDisconnect()

Disconnects the host computer.

Table 2-70 defines the return value.

Table 2-70 awDisconnect() return value

Return value Description

Boolean After calling this function, the calling program must delete

the object (C++ - delete IAwrem32X*, VB – set ObjectName
= Nothing;).

FileXferFromHost(HostFile, RemoteFile)

Copies a file from the host computer to the remote computer. The parameters
can contain wildcard characters.

Table 2-71 defines the FileXferFromHost parameters.

Table 2-71 FileXferFromHost parameters

Parameter Description

HostFile as string Contains the fully qualified path and file name to be copied

from the host computer.

RemoteFile as string Contains the fully qualified destination path and file

name. The HostFile and RemoteFile strings do not have to
be identical.

Table 2-72 defines the FileXferFromHost return value.

Table 2-72 FileXferFromHost return value

Return value Description

Boolean TRUE if command executed

FileXferToHost(HostFile, RemoteFile)

Copies a file from the remote computer to the host computer. The parameters
can contain wildcard characters.

Table 2-73 defines the FileXferToHost parameters.

Table 2-73 FileXferToHost parameters

Parameter Description

HostFile as string Contains the fully qualified destination path and file name.

RemoteFile as string Contains the fully qualified path and file name to be copied

from the remote computer. The HostFile and RemoteFile
strings do not have to be identical.

Table 2-74 defines the FileXferToHost return value.

Table 2-74 FileXferToHost return value

65Visual Basic object definitions

Awrem32 functions

Return value Description

Boolean TRUE if command executed

CreateFolderOnHost(FolderName)

Creates a new folder on the host computer. This function creates a temporary
folder on the remote computer, and then copies that folder to the host computer.

Table 2-75 defines the CreateFolderOnHost parameter.

Table 2-75 CreateFolderOnHost parameter

Parameter Description

FolderName as string Contains the drive and path to create the folder on the host

Table 2-76 defines the CreateFolderOnHost return values.

Table 2-76 CreateFolderOnHost return values

Return value Description

computer

Boolean TRUE if command executed

66 Visual Basic object definitions

Awrem32 functions

ExecuteHostFile(FileName)

Executes an existing file on the host computer. This function only executes
batch, command, and executable files. It does not execute files that are
associated with executables. For example, this function does not open Microsoft
Word if you execute a .doc file.

Table 2-77 defines the ExecuteHostFile parameter.

Table 2-77 ExecuteHostFile parameter

Parameter Description

FileName as string Contains the fully qualified path to the file on the host

Table 2-78 defines the ExecuteHostFile return value.

Table 2-78 ExecuteHostFile return value

computer

GetError()

Return value Description

Boolean TRUE if command executed

Returns the last error as a string.

Table 2-79 defines the return value.

Table 2-79 GetError() return value

Return value Description

String Returns the last error generated in Awrem32

ConnectionStatus()

Returns the current status of your connection to the host computer.

Table 2-80 defines the return value.

Table 2-80 ConnectionStatus() return value

Return value Description

Short The possible values include the following:

67Visual Basic object definitions

Awrem32 functions

■ -1 = Lost connection

■ 0 = No connection

■ 1 = Session connected

68 Visual Basic object definitions

Awrem32 functions

Visual C++ object
definitions

This chapter includes the following topics:

■ About Visual C++ objects

■ CRemoteDataManager methods

Chapter

3

■ CRemoteData object

■ CRemoteDataEx object

■ CHostDataManager methods

■ CHostData object

■ CHostDataEx object

■ Awrem32 functions

About Visual C++ objects

The pcAnywhere Automation Server provides the following components to
support OLE Automation:

■ Winawsvr: Provides the information needed to connect to the pcAnywhere

Automation Server and access its interfaces

■ Awrem32: Provides the information needed to control pcAnywhere

connections

70 Visual C++ object definitions

About Visual C++ objects

The objects that are described in Table 3-1 comprise Winawsvr.

Table 3-1 Winawsvr objects

Object Description Reference

CRemoteDataManager Provides the methods for

creating, opening, modifying,
saving, and deleting
CRemoteData objects

CRemoteData Defines the parameters for

accessing and controlling
pcAnywhere remote
functionality

CHostDataManager Provides the methods for

creating, opening, modifying,
saving, and deleting CHostData
objects

CHostData Defines the parameters for

accessing and controlling
pcAnywhere host functionality

See “CRemoteDataManager

methods” on page 71.

See “CRemoteData object”
on page 77.

See “CRemoteDataEx

object” on page 85.

See “CHostDataManager

methods” on page 86.

See “CRemoteData object”
on page 77.

See “CRemoteDataEx

object” on page 85.

Awrem32 has one object, which consists of eight interfaces to support remote
control and file transfer sessions.

See “Awrem32 functions” on page 104.

Some functions are no longer supported. However, object definitions are
provided for use with earlier versions.

For functions that require passwords, password values can be set but not
retrieved. This is for security purposes.

CRemoteDataManager methods

The CRemoteDataManager methods provide the parameters and return values
for accessing and controlling CRemoteData objects.

BSTR CurrentDirectory();

Gets the full path name of the current directory in which pcAnywhere remote
objects are stored.

Table 3-2 defines the parameter.

Table 3-2 BSTR CurrentDirectory(); parameter

Parameter Description

BSTR The full path name of the current pcAnywhere data

directory

71Visual C++ object definitions

CRemoteDataManager methods

BOOL ChangeDirectory(LPCTSTR lpszNewDirectory);

Changes the current directory in which pcAnywhere remote objects are stored.

Table 3-3 defines the parameter.

Table 3-3 BOOL ChangeDirectory parameter

Parameter Description

LPCTSTR lpszNewDirectory Name of an existing directory

Table 3-4 defines the return value.

Table 3-4 BOOL ChangeDirectory return value

Return value Description

BOOL TRUE if successful

72 Visual C++ object definitions

CRemoteDataManager methods

BOOL FindFirst(LPCTSTR lpszPattern, BSTR FAR*
pbstrFullQualName);

Finds the first pcAnywhere remote object file (*.chf) in the current directory,
based on the specified file name pattern.

Table 3-5 defines the parameters.

Table 3-5 BOOL FindFirst parameters

Parameter Description

LPCTSTR lpszPattern File name pattern to filter object files (an asterisk [*]

finds all files in the current directory)

BSTR FAR * pbstrFullQualName Return buffer for the full path name of the remote

object file that matches the specified pattern

Table 3-6 defines the return value.

Table 3-6 BOOL FindFirst return value

Return value Description

BOOL TRUE if a remote object file matching the specified

pattern is found. The full path name of the matching
file is stored in pbstrFullQualName.

BOOL FindNext(BSTR FAR* pbstrFullQualName);

After FindFirst() has been successfully called to get the name of a remote object
file in the current directory, FindNext() can be called to find the next file that
matches the pattern, if any.

Table 3-7 defines the parameter.

Table 3-7 BOOL FindNext parameter

Parameter Description

BSTR FAR * pbstrFullQualName Return buffer for the full path name of the remote

object file that matches the pattern specified in the
original call to FindFirst()

CRemoteDataManager methods

Table 3-8 defines the return value.

Table 3-8 BOOL FindNext return value

Return value Description

BOOL TRUE if another remote object file matching the

pattern specified in the call to FindFirst() is found.
The full path name of the matching file is stored in
pbstrFullQualName.

LPDISPATCH RetrieveObject(LPCTSTR lpszFQName, short
wAccessMode, LPCTSTR lpszPassword);

Retrieves a CRemoteData object by file name.

Table 3-9 defines the parameters.

Table 3-9 LPDISPATCH Retrieve Object parameters

73Visual C++ object definitions

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file name to be

loaded.

short wAccessMode Specifies how this object is to be used. This relates to

the password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

LPCTSTR lpszPassword Object password. May be NULL.

LPDISPATCH RetrieveObjectEx(LPCTSTR lpszFQName, short
wAccessMode, LPCTSTR lpszPassword);

Retrieves a CRemoteDataEx object by file name.

Table 3-10 defines the parameters.

Table 3-10 LPDISPATCH RetrieveObjectEx parameters

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file name to be

loaded.

74 Visual C++ object definitions

CRemoteDataManager methods

Table 3-10 LPDISPATCH RetrieveObjectEx parameters

Parameter Description

short wAccessMode Specifies how this object is to be used. This relates to

LPCTSTR lpszPassword Object password. May be NULL.

Table 3-11 defines the return value.

Table 3-11 LPDISPATCH RetrieveObjectEx return value

Return value Description

the password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CRemoteDataEx object.

For an example of how to attach this pointer to a
CRemoteDataEx object, see “Visual C++ sample code

for remote functionality” on page 85.

LPDISPATCH CreateObject(LPCTSTR lpszFQName);

Creates a CRemoteData object and returns an LPDISPATCH pointer to it.

Table 3-12 defines the parameter.

Table 3-12 LPDISPATCH CreateObject parameter

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file name for the

new object

CRemoteDataManager methods

Table 3-13 defines the return value.

Table 3-13 LPDISPATCH CreateObject return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CRemoteData object.

For an example of how to attach this pointer to a
CRemoteData object, see “Visual C++ sample code for

remote functionality” on page 85.

LPDISPATCH CreateObjectEx(LPCTSTR lpszFQName);

Creates a CRemoteDataEx object and returns an LPDISPATCH pointer to it.

Table 3-14 defines the parameter.

Table 3-14 LPDISPATCH CreateObjectEx parameter

75Visual C++ object definitions

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file name for the

new object

Table 3-15 defines the return value.

Table 3-15 LPDISPATCH CreateObjectEx return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CRemoteDataEx object.

For an example of how to attach this pointer to a
CRemoteDataEx object, see “Visual C++ sample code

for remote functionality” on page 85.

76 Visual C++ object definitions

CRemoteDataManager methods

BOOL DeleteObject(LPCTSTR lpszFQName, LPCTSTR lpszPassword);

Deletes a remote object file.

Table 3-16 defines the parameters.

Table 3-16 BOOL DeleteObject parameters

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file name of the

object to be deleted.

LPCTSTR lpszPassword Object password. May be NULL.

Table 3-17 defines the return value.

Table 3-17 BOOL DeleteObject return value

Return value Description

BOOL TRUE if object is deleted

BOOL Launch(LPCTSTR lpszFQName);

Launches a remote object file, which opens the pcAnywhere remote terminal
window.

Table 3-18 defines the parameter.

Table 3-18 BOOL Launch parameter

Parameter Description

LPCTSTR lpszFQName The fully qualified remote object file of object to be

launched

Table 3-19 defines the return value.

Table 3-19 BOOL Launch return value

Return value Description

BOOL TRUE if object is successfully launched

CRemoteData object

Use this object to modify remote object data.

Get and Set methods

The following methods are used to get and set properties of the CRemoteData
object.

The computer name is the name of the pcAnywhere host computer to be called
when the remote object is launched.

BSTR GetComputerName();
void SetComputerName(LPCTSTR lpszNewValue);

The phone number is the number to dial to establish a modem connection to a
pcAnywhere host computer.

BSTR GetPhoneNumber();
void SetPhoneNumber(LPCTSTR lpszNewValue);

77Visual C++ object definitions

CRemoteData object

Indicates whether TAPI dialing properties should be used (location information)
(TRUE) or whether the phone number string should be used exactly as it appears
(FALSE).

BOOL GetUseDialingProperties();
void SetUseDialingProperties(BOOL bNewValue);

If dialing properties are to be used, this is the area code of the number to be
called.

BSTR GetAreaCode();
void SetAreaCode(LPCTSTR lpszNewValue);

If dialing properties are to be used, this is the country code of the number to be
called.

BSTR GetCountryCode();
void SetCountryCode(LPCTSTR lpszNewValue);

The number of times to retry dialing this number if the call fails.

short GetRedialCount();
void SetRedialCount(short nNewValue);

The time to wait (in seconds) between redial attempts.

short GetRedialDelay();
void SetRedialDelay(short nNewValue);

The login name to be sent to the host when a connection is made. If this is left
empty, the user is prompted for a login name on connection.

78 Visual C++ object definitions

CRemoteData object

The login password to be sent to the host when a connection is made. If this is
left empty, the user is prompted for a password on connection.

The password for this object.

The object can only be launched if the password is used (TRUE).

The object can only be viewed if the correct password is provided (TRUE).

BSTR GetAutoLoginName();
void SetAutoLoginName(LPCTSTR lpszNewValue);

BSTR GetAutoLoginPassword();
void SetAutoLoginPassword(LPCTSTR lpszNewValue);

BSTR GetPassword();
void SetPassword(LPCTSTR lpszNewValue);

BOOL GetExecuteProtection();
void SetExecuteProtection(BOOL bNewValue);

BOOL GetReadProtection();
void SetReadProtection(BOOL bNewValue);

The object can only be written if the correct password is provided (TRUE).

BOOL GetWriteProtection();
void SetWriteProtection(BOOL bNewValue);

Controls whether sessions using this object are logged.

BOOL GetLogSession();
void SetLogSession(BOOL bNewValue);

Controls whether sessions using this object are recorded from the beginning.

BOOL GetRecordSession();
void SetRecordSession(BOOL bNewValue);

The name of the record file for sessions using this object.

BSTR GetRecordFile();
void SetRecordFile(LPCTSTR lpszNewValue);

Sets the connection types.

BOOL GetRunOnConnect();
void SetRunOnConnect(BOOL bNewValue);

The following connection types are available:

■ COM1

■ COM2

■ COM3

CRemoteData object

■ COM4

■ Infrared

■ ISDN via CAPI 2.0

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ NetBIOS

■ SPX

■ DEFAULT TAPI

■ TCP/IP

The name of a TAPI device can also be used as a connection type. DEFAULT
TAPI uses the first TAPI device found on the system. To use a specific TAPI
device, use FirstConnectionType() / NextConnectionType() to search for
available devices.

79Visual C++ object definitions

Remote object Detail methods

When a remote object is assigned a connection type, the device details are set to
valid default values. The following connection types have advanced
configuration options that can be set in your application:

■ COM devices

■ NetBIOS devices

■ ISDN via CAPI 2.0 (European ISDN only) devices

COM device details

Sets the communications parity level.

BSTR GetComParity();
void SetComParity(LPCTSTR lpszNewValue);

Communications parity values are as follows:

■ None

■ Odd

■ Even

■ Mark

80 Visual C++ object definitions

CRemoteData object

■ Space

Sets the flow control level.

Flow control values are as follows:

■ <None>

■ XONXOFF

■ RTS/CTS

■ BOTH

Sets the connection start setting.

Connection start values are as follows:

BSTR GetComFlowControl();
void SetComFlowControl(LPCTSTR lpszNewValue);

BSTR GetComStartedBy();
void SetComStartedBy(LPCTSTR lpszNewValue);

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>'s

■ Modem response

Sets the connection end values.

BSTR GetComEndedBy();
void SetComEndedBy(LPCTSTR lpszNewValue);

Connection end values are as follows:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

Sets the connection speed.

long GetComSpeed();
void SetComSpeed(long nNewValue);

Connection speed values are as follows:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

■ 9600

■ 19200

81Visual C++ object definitions

CRemoteData object

■ 38400

■ 57600

■ 115200

NetBIOS device details

Sets the LAN Adapter (LANA) number to use for this connection.

short GetLanaNumber();
void SetLanaNumber(short nNewValue);

ISDN via CAPI 2.0 device details

Activates channel bonding (uses two ISDN channels for one connection) if
TRUE.

BOOL GetCapiChannelBonding();
void SetCapiChannelBonding(BOOL bNewValue);

Sets any additional CAPI extensions that are needed for communications.

BSTR GetCapiExtensions();
void SetCapiExtensions(LPCTSTR lpszNewValue);

82 Visual C++ object definitions

CRemoteData object

Remote object methods

The following are the normal methods of the remote object (they are not used to
get and set properties):

■ short ConnectionTypes();

■ BSTR FirstConnectionType(); and BSTR NextConnectionType();

■ BOOL FindConnectionType(LPCTSTR lpszConnectionType);

■ short CountryCodes();

■ BSTR FirstCountryCode(); and BSTR NextCountryCode();

■ BOOL ReadObject(LPCTSTR lpszPassword);

■ BOOL WriteObject(LPCTSTR lpszPassword);

short ConnectionTypes();

Returns the number of connection types available.

Table 3-20 defines the return value.

Table 3-20 short ConnectionTypes(); return value

Return value Description

Short The number of connection types available on this

computer

BSTR FirstConnectionType(); and BSTR
NextConnectionType();

FirstConnectionType() and NextConnectionType() are used to iterate through
the available connection types. These functions return a BSTR, which is the
name of an available connection type. You can use these returned connection
types with the SetConnectionType() function.

Table 3-21 defines the return value.

Table 3-21 BSTR FirstConnectionType(); and BSTR NextConnectionType();

return value

Return value Description

BSTR The name of a supported connection device type

CRemoteData object

BOOL FindConnectionType(LPCTSTR lpszConnectionType);

Returns TRUE if the connection type that is passed in exists on the computer.

Table 3-22 defines the parameter.

Table 3-22 BOOL FindConnectionType parameter

Parameter Description

LPCTSTR lpszConnectionType The name of a connection device type

Table 3-23 defines the return value.

Table 3-23 BOOL FindConnectionType return value

Return value Description

BOOL TRUE if this device type is available

83Visual C++ object definitions

short CountryCodes();

Returns the number of country codes available.

Table 3-24 defines the return value.

Table 3-24 short CountryCodes(); return value

Return value Description

Short The number of country codes available

BSTR FirstCountryCode(); and BSTR NextCountryCode();

FirstCountryCode() and NextCountryCode() are used to iterate through the
available country codes. These functions return a BSTR, which is the name of an
available country code. You can use these returned values with the
SetCountryCode() function.

Table 3-25 defines the return value.

Table 3-25 BSTR FirstCountryCode(); and BSTR NextCountryCode(); return

value

Return value Description

BSTR The first or next country code string

84 Visual C++ object definitions

CRemoteData object

BOOL ReadObject(LPCTSTR lpszPassword);

Reads the object data from the remote object file.

Table 3-26 defines the parameter.

Table 3-26 BOOL ReadObject parameter

Parameter Description

LPCTSTR lpszPassword The object password

Table 3-27 defines the return value.

Table 3-27 BOOL ReadObject return value

Return value Description

BOOL TRUE if object is successfully read

BOOL WriteObject(LPCTSTR lpszPassword);

Writes the object data out to the remote object file.

Table 3-28 defines the parameter.

Table 3-28 BOOL WriteObject parameter

Parameter Description

LPCTSTR lpszPassword The object password

Table 3-29 defines the return value.

Table 3-29 BOOL WriteObject return value

Return value Description

BOOL TRUE if object is successfully written

CRemoteDataEx object

The CRemoteDataEx object contains the same functionality as the CRemoteData
object with the following additional Get and Set methods:

BSTR GetPrivateKey(); //Returns the PrivateKey information
void SetPrivateKey(LPCTSTR lpszNewValue);
BSTR GetCertificationName(); //Returns the Certification Name
void SetCertificationName(LPCTSTR lpszNewValue);
short GetEncryptionLevel(); //Returns the encryption level value
void SetEncryptionLevel(short nNewValue);
BOOL GetDenyLowerEncrypt(); //Returns the DenyLowerEncrypt value
void SetDenyLowerEncrypt(BOOL bNewValue);
BSTR GetAutoDomain(); //Returns the AutoDomain value
void SetAutoDomain(LPCTSTR lpszNewValue);

85Visual C++ object definitions

CRemoteDataEx object

Visual C++ sample code for remote functionality

The following sample C++ function creates a remote object, sets its connection
type to TCP/IP, sets the computer name to the TCP/IP address passed into the
function, and then launches the remote object:

BOOL LaunchTCPRemote(LPCTSTR lpszAddress)
{
BOOL bReturn = FALSE;

CRemoteDataManager remoteDM;

CRemoteData remoteData;

// First, create the CRemoteDataManager
remoteDM.CreateDispatch( _T( “WINAWSVR.RemoteDataManager”) );
// Next, create CRemoteData and attach it
remoteData.AttachDispatch( remoteDM.CreateObject(“Test”, 0) );

// Now, set the required properties
remoteData.SetConnectionType(“TCP/IP”);

remoteData.SetComputerName(lpszAddress);

// Save the object data
if (remoteData.WriteObject(0))

86 Visual C++ object definitions

CHostDataManager methods

{
// And launch it
if (remoteData.Launch())

bReturn = TRUE;

}
// Release the remote object.
remoteData.ReleaseDispatch();

remoteDM.ReleaseDispatch( _T( “WINAWSVR.RemoteDataManager”) );

return bReturn;

}

CHostDataManager methods

The CHostDataManager methods provide the parameters and return values for
accessing and controlling CHostData objects.

BSTR CurrentDirectory();

Returns the full path name of the current directory in which pcAnywhere host
objects are stored.

Table 3-30 defines the return value.

Table 3-30 BSTR CurrentDirectory(); return value

Return value Description

BSTR The full path name of the current pcAnywhere data

directory

BOOL ChangeDirectory(LPCTSTR lpszNewDirectory);

Changes the current directory in which pcAnywhere host objects are stored.

Table 3-31 defines the parameter.

Table 3-31 BOOL ChangeDirectory parameter

Parameter Description

LPCTSTR lpszNewDirectory Name of an existing directory

Table 3-32 defines the return value.

Table 3-32 BOOL ChangeDirectory return value

Return value Description

BOOL TRUE if successful

BOOL FindFirst(LPCTSTR lpszPattern, BSTR FAR*
pbstrFullQualName);

Finds the first pcAnywhere host object file (*.bhf) in the current directory, based
on the specified file name pattern.

Table 3-33 defines the parameters.

Table 3-33 BOOL FindFirst parameters

Parameter Description

87Visual C++ object definitions

CHostDataManager methods

LPCTSTR lpszPattern File name pattern to filter object files (an asterisk [*]

finds all host files in the current directory)

BSTR FAR * pbstrFullQualName Return buffer for the full path name of the remote

object file that matches the specified pattern

Table 3-34 defines the return value.

Table 3-34 BOOL FindFirst return value

Return value Description

BOOL TRUE if a host object file matching the specified

pattern is found. The full path name of the matching
file is stored in pbstrFullQualName.

BOOL FindNext(BSTR FAR* pbstrFullQualName);

After FindFirst() has been successfully called to get the name of a host object file
in the current directory, FindNext() can be called to find the next file that
matches the pattern, if any.

88 Visual C++ object definitions

CHostDataManager methods

Table 3-35 defines the parameter.

Table 3-35 BOOL FindNext parameter

Parameter Description

BSTR FAR * pbstrFullQualName Return buffer for the full path name of the host object

Table 3-36 defines the return value.

Table 3-36 BOOL FindNext return value

Return value Description

BOOL TRUE if another host object file matching the pattern

file that matches the pattern specified in the original
call to FindFirst()

specified in the call to FindFirst() is found. The full
path name of the matching file is stored in
pbstrFullQualName.

LPDISPATCH RetrieveObject(LPCTSTR lpszFQName, short
wAccessMode, LPCTSTR lpszPassword);

Retrieves a CHostData object by file name.

Table 3-37 defines the parameters.

Table 3-37 LPDISPATCH RetrieveObject parameters

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file name to be loaded.

short wAccessMode Specifies how this object is to be used. This relates to

the password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

LPCTSTR lpszPassword Object password. May be NULL.

CHostDataManager methods

Table 3-38 defines the return value.

Table 3-38 LPDISPATCH RetrieveObject return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CHostData object.

For an example of how to attach this pointer to a
CHostData object, see “Visual C++ sample code for

host functionality” on page 103.

LPDISPATCH RetrieveObjectEx(LPCTSTR lpszFQName, short
wAccessMode, LPCTSTR lpszPassword);

Retrieves a CHostDataEx object by file name.

Table 3-39 defines the parameters.

89Visual C++ object definitions

Table 3-39 LPDISPATCH RetrieveObjectEx parameters

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file name to be loaded.

short wAccessMode Specifies how this object is to be used. This relates to

the password protection. The options are as follows:

■ 0 = Not specified

■ 1 = View only

■ 2 = View and Modify

■ 3 = Execute

LPCTSTR lpszPassword Object password. May be NULL.

Table 3-40 defines the return value.

Table 3-40 LPDISPATCH RetrieveObjectEx return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CHostDataEx object.

For an example of how to attach this pointer to a
CHostDataEx object, see “Visual C++ sample code for

host functionality” on page 103.

90 Visual C++ object definitions

CHostDataManager methods

LPDISPATCH CreateObject(LPCTSTR lpszName);

Creates a CHostData object and returns an LPDISPATCH pointer to it.

Table 3-41 defines the parameter.

Table 3-41 LPDISPATCH CreateObject parameter

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file name for the new

object

Table 3-42 defines the return value.

Table 3-42 LPDISPATCH CreateObject return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CHostData object.

For an example of how to attach this pointer to a
CHostData object, see “Visual C++ sample code for

host functionality” on page 103.

LPDISPATCH CreateObjectEx(LPCTSTR lpszName);

Creates a CHostDataEx object and returns an LPDISPATCH pointer to it.

Table 3-43 defines the parameter.

Table 3-43 LPDISPATCH CreateObjectEx parameter

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file name for the new

object

Table 3-44 defines the return value.

Table 3-44 LPDISPATCH CreateObjectEx return value

Return value Description

LPDISPATCH Pointer to an OLE dispatch object. The object is a

CHostDataEx object.

For an example of how to attach this pointer to a
CHostDataEx object, see “Visual C++ sample code for

host functionality” on page 103.

CHostDataManager methods

BOOL DeleteObject(LPCTSTR lpszFQName, LPCTSTR lpszPassword);

Deletes a host object file.

Table 3-45 defines the parameters.

Table 3-45 BOOL DeleteObject parameters

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file name of the object

to be deleted.

LPCTSTR lpszPassword Object password. May be NULL.

Table 3-46 defines the return value.

Table 3-46 BOOL DeleteObject return value

Return value Description

91Visual C++ object definitions

BOOL TRUE if object is deleted

BOOL Launch(LPCTSTR lpszFQName);

Launches a host object file, which opens the pcAnywhere host terminal window.

Table 3-47 defines the parameter.

Table 3-47 BOOL Launch parameter

Parameter Description

LPCTSTR lpszFQName The fully qualified host object file of object to be

launched

Table 3-48 defines the return value.

Table 3-48 BOOL Launch return value

Return value Description

BOOL TRUE if object is successfully launched

92 Visual C++ object definitions

CHostData object

CHostData object

Use this object to modify host object data.

Get and Set methods

The following methods are used to get and set properties of the CHostData
object.

The phone number is the number to dial to establish a modem connection to a
pcAnywhere remote computer.

BSTR GetPhoneNumber();
void SetPhoneNumber(LPCTSTR lpszNewValue);

Indicates whether TAPI dialing properties should be used (location information)
(TRUE) or whether the phone number string should be used exactly as it appears
(FALSE).

BOOL GetUseDialingProperties();
void SetUseDialingProperties(BOOL bNewValue);

If dialing properties are to be used, this is the area code of the number to be
called.

BSTR GetAreaCode();
void SetAreaCode(LPCTSTR lpszNewValue);

If dialing properties are to be used, this is the country code of the number to be
called.

BSTR GetCountryCode();
void SetCountryCode(LPCTSTR lpszNewValue);

The number of times to retry dialing this number if the call fails.

short GetRedialCount();
void SetRedialCount(short nNewValue);

The time to wait (in seconds) between redial attempts.

short GetRedialDelay();
void SetRedialDelay(short nNewValue);

Controls whether sessions using this object are logged.

BOOL GetLogSession();
void SetLogSession(BOOL bNewValue);

Controls whether sessions using this object are recorded from the beginning.

BOOL GetRecordSession();
void SetRecordSession(BOOL bNewValue);

The name of the record file for sessions using this object.

BSTR GetRecordFile();
void SetRecordFile(LPCTSTR lpszNewValue);

Host object Detail methods

When a host object is assigned a connection type, the device details are set to
valid default values. The following connection types have advanced
configuration options that can be set in your application:

■ COM devices

■ NetBIOS devices

■ NASI/NCSI devices

■ ISDN via CAPI 2.0 (European ISDN only) devices

93Visual C++ object definitions

CHostData object

COM device details

The following code places the requested connection type on the host object’s list
of assigned connection types and makes it the current connection type when
processing subsequent device-specific method calls:

BOOL AssignConnection(LPCTSTR lpszNewValue);

If the requested connection type is already on the list of assigned connections,
the list of assigned connections does not change. Only the current connection
type is changed to the requested type. It is normal to call the AssignConnection
method on the same object multiple times in the course of getting and setting
connection-specific values.

AssignConnection returns TRUE if the connection type that is passed in exists
on the computer and is either successfully assigned or already assigned. It
returns FALSE if either the requested connection type does not exist on the
computer or the current assigned connection count is already at the maximum
allowed level.

A pcAnywhere host object can support up to two assigned connection types. The
AssignConnection method returns FALSE if it detects an attempt to exceed this
limit.

The following connection types are available:

■ COM1

■ COM2

■ COM3

■ COM4

94 Visual C++ object definitions

CHostData object

■ SPX

■ NetBIOS

■ TCP/IP

■ LPT1

■ LPT2

■ LPT3

■ LPT4

■ ISDN via CAPI 2.0

■ Infrared

■ DEFAULT TAPI

The name of a TAPI device can also be used as a connection type. DEFAULT
TAPI uses the first TAPI device found in the system. To use a specific TAPI
device, use FirstConnectionType() and NextConnectionType() to search for
available devices.

The following code unassigns a connection type. After unassigning a connection
type, the remaining assigned connection, if any, becomes the current
connection type for subsequent device-specific method calls.

BOOL UnassignConnection(LPCTSTR lpszNewValue);

The following code sets the communications parity levels:

BSTR GetComParity();
void SetComParity(LPCTSTR lpszNewValue);

Communication parity values are as follows:

■ None

■ Odd

■ Even

■ Mark

■ Space

The following code sets the flow control levels:

BSTR GetComFlowControl();void SetComFlowControl(LPCTSTR
lpszNewValue);

Flow control values are as follows:

■ <None>

■ XONXOFF

■ RTS/CTS

■ BOTH

The following code sets the connection start values:

BSTR GetComStartedBy();
void SetComStartedBy(LPCTSTR lpszNewValue);

Connection start values are as follows:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

■ Receive 2 <CR>'s

95Visual C++ object definitions

CHostData object

■ Modem response

The following code sets the connection end values:

BSTR GetComEndedBy();
void SetComEndedBy(LPCTSTR lpszNewValue);

Connection end values are as follows:

■ Always connected

■ Carrier detect (DCD)

■ Clear to send (CTS)

■ Data set ready (DSR)

■ Ring indicator (RI)

The following code sets the connection speed:

long GetComSpeed();
void SetComSpeed(long nNewValue);

Connection speed values are as follows:

■ 110

■ 300

■ 600

■ 1200

■ 2400

■ 4800

96 Visual C++ object definitions

CHostData object

■ 9600

■ 19200

■ 38400

■ 57600

■ 115200

NetBIOS device details

Sets the LAN Adapter (LANA) number to use for this connection.

NASI/NCSI device details

Sets the user name for the NASI server.

short GetLanaNumber();void SetLanaNumber(short nNewValue);

BSTR GetNasiUserName();
void SetNasiUserName(LPCTSTR lpszNewValue);

Sets the user password for NASI server.

BSTR GetNasiPassword();
void SetNasiPassword(LPCTSTR lpszNewValue);

Sets the NASI session name.

BSTR GetNasiSessionName();
void SetNasiSessionName(LPCTSTR lpszNewValue);
BOOL GetNasiSessionNameAvailable();
void SetNasiSessionNameAvailable(BOOL bNewValue);

Specifies the NASI server to use.

BOOL NasiServer();
BSTR GetNasiServerName();
void SetNasiServerName(LPCTSTR lpszNewValue);

Specifies the NASI Service to use.

BOOL NasiService();
BSTR GetNasiServiceName();
void SetNasiServiceName(LPCTSTR lpszNewValue);

Specifies the NASI Port to use.

BOOL NasiPort();
BSTR GetNasiPortName();
void SetNasiPortName(LPCTSTR lpszNewValue);
BOOL GetNasiSelectOnConnect();

void SetNasiSelectOnConnect(BOOL bNewValue);

ISDN via CAPI 2.0 device details

Activates channel bonding (uses two ISDN channels for one connection) if
TRUE.

BOOL GetCapiChannelBonding();
void SetCapiChannelBonding(BOOL bNewValue);

Sets any additional CAPI extensions that are needed for communications.

BSTR GetCapiExtensions();
void SetCapiExtensions(LPCTSTR lpszNewValue);

Host object methods

The following are the normal methods of the object (they are not used to get and
set properties):

97Visual C++ object definitions

CHostData object

■ short ConnectionTypes();

■ BSTR FirstConnectionType(); and BSTR NextConnectionType();

■ BOOL FindConnectionType(LPCTSTR lpszConnectionType);

■ short MaxAssignedConnections()

■ short AssignedConnections()

■ BSTR FirstAssignedConnection(); and BSTR NextAssignedConnection();

■ BOOL FindAssignedConnection (LPCTSTR lpszConnectionType);

■ short CountryCodes();

■ BSTR FirstCountryCode(); and BSTR NextCountryCode();

■ BOOL ReadObject(LPCTSTR lpszPassword);

■ BOOL WriteObject(LPCTSTR lpszPassword);

short ConnectionTypes();

Returns the number of connection types available.

Table 3-49 defines the return value.

Table 3-49 short Connection Types(); return value

Return value Description

Short The number of connection types available on this

computer

98 Visual C++ object definitions

CHostData object

BSTR FirstConnectionType(); and BSTR
NextConnectionType();

FirstConnectionType() and NextConnectionType() are used to iterate through
the available connection types. The functions return a BSTR, which is the name
of an available connection type. You can use these returned connection types
with the SetConnectionType() function.

Table 3-50 defines the return value.

Table 3-50 BSTR FirstConnectionType(); and BSTR NextConnectionType();

Return value Description

BSTR The name of a supported connection device type

BOOL FindConnectionType(LPCTSTR lpszConnectionType);

return value

Returns TRUE if the connection type that is passed in exists on the computer.

Table 3-51 defines the parameter.

Table 3-51 BOOL FindConnectionType parameter

Parameter Description

LPCTSTR lpszConnectionType The name of a connection device type

Table 3-52 defines the return value.

Table 3-52 BOOL FindConnectionType return value

Return value Description

BOOL TRUE if this device type is available

short MaxAssignedConnections()

Returns the maximum number of connection types that can be assigned at the
same time (currently two).

Table 3-53 defines the return value.

Table 3-53 short MaxAssignedConnections() return value

Return value Description

Short The maximum number of connection type

assignments

CHostData object

short AssignedConnections()

Returns the number of assigned connection types.

Table 3-54 defines the return value.

Table 3-54 short AssignedConnections() return value

Return value Description

Short The number of assigned connection types on this

computer

BSTR FirstAssignedConnection(); and
BSTR NextAssignedConnection();

FirstAssignedConnection() and NextAssignedConnection() are used to iterate
through the list of assigned connections. These functions return a BSTR, which
is the name of an assigned connection type. You can use these returned
connection types with the AssignConnection() function.

99Visual C++ object definitions

Table 3-55 defines the return value.

Table 3-55 BSTR FirstAssignedConnection(); and BSTR

NextAssignedConnection(); return value

Return value Description

BSTR The name of a supported connection device type

BOOL FindAssignedConnection (LPCTSTR
lpszConnectionType);

Returns TRUE if the connection type that is passed in is currently assigned on
the computer.

Table 3-56 defines the parameter.

Table 3-56 BOOL FindAssignedConnection parameter

Parameter Description

LPCTSTR lpszConnectionType The name of a connection device type

100 Visual C++ object definitions

CHostData object

Table 3-57 defines the return value.

Table 3-57 BOOL FindAssignedConnection return value

Return value Description

BOOL TRUE if this device type is currently assigned

short CountryCodes();

Returns the number of country codes available.

Table 3-58 defines the return value.

Table 3-58 short CountryCodes(); return value

Return value Description

Short The number of country codes available

BSTR FirstCountryCode(); and BSTR NextCountryCode();

FirstCountryCode() and NextCountryCode() are used to iterate through the list of
available country codes. The functions return a BSTR, which is the name of an
available country code. You can use these returned values with the
SetCountryCode() function.

Table 3-59 defines the return value.

Table 3-59 BSTR FirstCountryCode(); and BSTR NextCountryCode(); return

value

Return value Description

BSTR The first or next country code string

BOOL ReadObject(LPCTSTR lpszPassword);

Reads the object data from the host object file.

Table 3-60 defines the parameter.

Table 3-60 BOOL ReadObject parameter

Parameter Description

LPCTSTR lpszPassword The object password