RemoteWare API Manual. Version 4.1 Service Pack 1A

Transcription

1 RemoteWare API Manual Version 4.1 Service Pack 1A

2 RemoteWare API Manual Version 4.1 Service Pack 1A This document was prepared to assist licensed users of RemoteWare by XcelleNet, Inc.; its contents may not be used for any other purpose without prior written permission. The material contained herein is supplied without representation or warranty of any kind and is based on typical use. Any unusual use may produce unpredictable results. XCELLENET ASSUMES NO RESPONSIBILITY AND SHALL HAVE NO LIABILITY OF ANY KIND ARISING FROM THE SUPPLY OR USE OF THIS DOCUMENT OR THE MATERIAL CONTAINED HEREIN. Companies, names, information, and data used in examples herein are fictitious unless otherwise noted. The information in this document is furnished for informational use only and is subject to change without notice. References in this manual to XcelleNet products, programs, or services do not imply that XcelleNet intends to make these available in all countries in which XcelleNet operates. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR XcelleNet, Inc. All Rights Reserved. All rights reserved, including the right to reproduce this document or any portion thereof in any form. Printed in the United States of America. RemoteWare is a trademark of XcelleNet, Inc. Other product and company names mentioned herein may be the brand names, trade names, trademarks or registered trademarks of their respective orders.

3 Contents USING THIS GUIDE About this guide... vii Working with an electronic guide... vii Using bookmarks and links... viii Using the Find feature... ix Printing this guide... x Using RemoteWare online Help... xi RemoteWare Support Services... xii What s in this guide... xiii Related publications... xiv Additional information sources... xvi CHAPTER 1: INSTALLING API FILES Supported environments Supported compilers Installing the API files from the CD-ROM Copying API files Testing your API programs Using the APIs with Visual Basic CHAPTER 2: USING THE API FUNCTIONS Error handling Types of errors Interpreting data types CHAPTER 3: SERVER API FUNCTIONS General notes New functions Building Server applications Error codes Server Alarm API functions Server worklist API functions Server Notify API functions... 51

4 iv RemoteWare API Manual Server database API functions Server Object API functions Server Schedule API function Server Information API function Server Reset Security API function CHAPTER 4: 16-BIT WINDOWS AND 32-BIT OS/2 CLIENT APIS General notes Compiling and linking applications for Windows Compiling and linking applications for OS/ Error codes Client Configuration and Status API functions Transaction Pipe API functions Transaction Pipe Notification Types Transaction Pipe Error Codes Client Worklist API functions Client Dialing Directory API functions Client Object API functions CHAPTER 5: DOS CLIENT APIS General notes Compiling and linking applications Error codes DOS Client Configuration and Status API functions CHAPTER 6: WORKLIST EVENTS Using worklists Client vs. Server worklist APIs Communicating between worklists and programs Worklist default files and paths File transfer events Operating system events Session control events Server events CHAPTER 7: WIN32 COM OBJECT CLIENT APIS

5 Contents v Overview of Win32 COM OBJECT Client APIs Interface Definition Language (IDL) Error handling Win32 Client API structure RWClient Object EnumRWClientInfo Object XWorkList Object RWClientInfo Object RWClientDialingEntry Object IRWClientDialingEntryCollection Object RWClientWOSelection Object IRWClient API Methods IRWClientInfo API Methods IRWClientDialingEntry API IRWClientSessionStatus API Methods IRWClientTextExplanation API Methods IRWClientDialingDirectory API Methods IRWClientSessionResultLog API Methods IRWClientStatus API methods IRWClientWOSelection API methods IRWClientDialingEntryCollection API Methods IRWClientInfoCollection API Methods Transaction Pipe API functions Transaction Pipe Notification Types Transaction Pipe function Error Codes IXWorkList API methods IRWClientStatusEvents API methods Enumerations and Structures Client ActiveX Controls APPENDIX A DIAL SCRIPTS Using DLLCALL INDEX

6 vi RemoteWare API Manual

7 Chapter X: Chapter Title <-- Apply chapter hidden style Using This Guide This guide introduces you to RemoteWare, a remote systems management tool specifically designed to distribute software to and perform inventory scans for remote and fixed-site users. It contains fundamental information necessary to use the software, including a conceptual overview and highly interactive walkthroughs. We recommend that you print this guide so that it is readily available as you perform your tasks. However, if you prefer to use this guide online, you may find it helpful to zoom to 150% for enhanced readability. For information on printing the guide, see Printing this guide on page x. About this guide This book is intended for the administrator who maintains the RemoteWare Server. Before working with RemoteWare, we strongly recommend that you possess a working knowledge of the Windows NT or Windows 2000 operating system. You should also be familiar with the operating environments which run the RemoteWare Clients. In addition, the RemoteWare system administrator should be familiar with Windows NT or Windows 2000 Server concepts such as services, networks, user and group account administration, domains, and system security. Working with an electronic guide If you re reading this guide right now, you re looking at it in Adobe Acrobat Reader. You might be tempted to print the document immediately, but wait Acrobat Reader actually has several features we ve incorporated into this document to make it easier to use electronically, including: Bookmarks for accessing task-driven topics, such as creating Client installation kits A hyperlinked Table of Contents and Index

8 viii RemoteWare AntiVirus Manager Administrator s Guide Links on the first page of each chapter that take you directly to the topic covered Hyperlinked cross references Acrobat also has several features that make it easy for you to access the information you need. See your Adobe Acrobat Reader online Help for more information. Using bookmarks and links We ve included bookmarks and links in the guide to search for topics. When you open the guide in Acrobat Reader, the Bookmarks and Page view automatically appears. Bookmarks You can access topics in the guide several different ways. You can click on any of the bookmark icons in the left pane to go directly to a topic. To see more topics, click the icon next to a bookmark. This will list all of the other topics covered in that section. To close the list, click the icon next to the bookmark. Links Table of Contents and Index Both the Table of Contents and the Index are hyperlinked, so you can click on a link and go straight to the information you need to access. In the Table of Contents, both the headings and the page numbers are linked. In the Index, only the page numbers are linked. To select a topic from the Table of Contents or the Index: 1 Select the Hand tool from the toolbar. The pointer symbol will change to a hand symbol. 2 Place the hand symbol over the heading or the page number containing the information you want to view and click. Acrobat Reader will take you to the page you selected.

9 Using This Guide ix Chapter introductions On the first page of each chapter, you ll see blue hyperlinks that lead you to various topics within that chapter. Use the hand tool to click on the link, and Acrobat Reader will take you to that topic. Cross-references You ll see blue hyperlinked cross-references throughout each chapter. Just use the hand tool to click on the link, and Acrobat Reader will take you to the next page. Using the Find feature You can use Acrobat s Find option to do a full-text search of any document you have open. To do a full-text search of the RemoteWare guide: 1 Click the Find toolbar button. The Find dialog box will appear. 2 In the Find What area, enter the term(s) you want to find. To close the Find dialog box, click Cancel at any time. 3 Select any of these check box options that apply: Match Whole Word Only. Select this option if you want Acrobat Reader to search for that exact term only. Match Case. Select this option to do a case-sensitive search for words. Find Backwards. Select this option if you want Acrobat Reader to move backwards instead of forwards when searching for a word. 4 Click Find to begin your search. Once Acrobat Reader finds the term, it will close the Find dialog box. 5 To continue searching for other instances of a term, select Find Again from the View menu. The Find dialog Box will reappear, with the original term still in the Find What area. 6 Click Find Again. Repeat this process until you ve found the section you want to view.

10 x RemoteWare AntiVirus Manager Administrator s Guide Printing this guide From Acrobat Reader you can print the entire guide or print a range of pages. To print the guide: 1 On the File menu, select Print. 2 Make sure you have the correct printer and number of copies selected, then click OK.

11 Using This Guide xi Using RemoteWare online Help RemoteWare contains online Help that provides explanations of features and steps for completing tasks. For more general information, see your Windows NT, 95/98, or 2000 online Help. To access RemoteWare online Help: On the Help menu, select RemoteWare Help. The main Help window will appear. Features in the RemoteWare online Help include: Table of Contents. Provides the Help file contents for the application you currently have open. Includes an introduction and task-driven topic headings. Index. Provides a quick link within to any topic within the application associated with the key word you select. Search. Allows you to search all the Help file contents by entering a word or phrase. Glossary. Provides short, concise definitions for key terms in the RemoteWare application. Internal links. Provide direct jumps to related other topics. Pop-up Help. Provides pop-up definitions of terms without requiring you to move to another topic or access the glossary.

12 xii RemoteWare AntiVirus Manager Administrator s Guide RemoteWare Support Services XcelleNet offers a variety of support options to help you get the most out of RemoteWare. If you have a question about the product, first look in the documentation or consult the online Help. If you can t find the answer, contact Customer Support. Customers who are on a maintenance plan with XcelleNet may contact Technical Support Monday through Friday from 8:30 A.M. to 8:30 P.M. EST for assistance. Call the Technical Support staff at toll free, in the Atlanta, Georgia area or for Europe, Middle East or Africa. You can find detailed information on obtaining Technical Support on XcelleNet s web site.

13 Using This Guide xiii What s in this guide This guide contains the chapters summarized in the table below. See the Contents for a full listing. Table 1. Chapters in this guide Chapter Title Chapter 1 Installing API Files Lists compiler requirements and provides instructions for installing the RemoteWare API files. Chapter 2 Using the API Functions Discusses issues and requirements for successfully using RemoteWare API functions. Chapter 3 Server API Functions Covers the Server API functions that run on the RemoteWare Server, including how to use the functions and interpret their return codes. Chapter 4 16-bit Windows and 32-bit OS/2 Client APIs Describes the APIs for use with the RemoteWare 16-bit Clients running under Windows 3.x, NT, or 95. Also explains the use of the OS/2 version of the APIs to build applications for OS/2 Nodes. Chapter 5 DOS Client APIs Describes the DOS Client API calls for the DOS programming environment and explains how to use the functions and interpret their return codes. Chapter 6 Worklist Events Describes the events that you can use to build a worklist. Chapter 7 Win32 COM Object Client APIs Describes the collection of Component Object Model (COM) objects that enable you to write programs that interact with XcelleNet s RemoteWare Client software. Appendix A Dial Scripts Describes the methods for using dial scripts to execute customized code.

14 xiv RemoteWare AntiVirus Manager Administrator s Guide Related publications In addition to this manual, the following related manuals are available in printed format from your RemoteWare representative. They are also available in electronic format on the RemoteWare CD-ROM as described in the following section. RemoteWare Server Administrator s Guide. Explains how to operate and maintain a RemoteWare system. It takes a task-oriented approach to describing features. RemoteWare Server Reference Guide. Contains a detailed description of every application, facility, window, menu, and control present in the RemoteWare Server. Use this book when you want to know what something does, how it is used, or why it behaves as it does. Electronic documentation The following documents are available on the RemoteWare CD. Unless otherwise specified, all documents reside in the \Documents directory. All electronic documents require the Adobe Acrobat reader to view and print PDF files. Install the reader from the RemoteWare CD using the\acroread\ar32e01.exe file. Administrator guides RemoteWare Workshop Developer s Guide. Explains how to use RemoteWare Workshop to create and publish customized desktop-style Workshop applications. RemoteWare Subscriber Administrator s Guide. Shows how to build and deploy lists of files and applications to the Client. It also explains how to use the Subscriber Lists at the RemoteWare Client. RemoteWare Inventory Manager Administrator s Guide. Explains how to use Inventory Manager for centralized monitoring and reporting of hardware and software resources on RemoteWare Clients. Instructions include how to create Inventory Manager Profiles that control the operating and scheduling of Client inventory scans, and how to assign those Profiles to Clients. The guide also describes how to view and interpret the centrally stored resource information for each Client. RemoteWare Software Manager Administrator s Guide. Explains how to use Software Manager to efficiently and securely distribute, install, and manage software for enterprise system users. Includes how to create and define software package contents and then assign that package to a RemoteWare Client. RemoteWare Migration Guide. Explains how to plan and implement many aspects of migration from RemoteWare for OS/2 to RemoteWare. RemoteWare Multicast System Administrator s Guide. Explains how to use RemoteWare Multicast. Multicast allows administrators to distribute files to a large

15 Using This Guide xv number of RemoteWare Clients with a single communication session from the Server. It contains fundamental information necessary to use the software, including a conceptual overview and highly interactive walkthroughs. RemoteWare ActiveX Controls Reference Manual. Presents the 32-bit ActiveX controls that are included with the RemoteWare 32-bit Client software. These controls add selected Client functionality to ActiveX or OLE container applications. RemoteWare Workshop Programmer s Guide. Describes optional programmatic extensions that enhance Workshop environments. Summit BasicScript Reference Manual and Summit BasicScript User s Guide provide information on the options and structure for RemoteWare scripting. These documents are available in the \Document\Development Tool Administrator Guides\Summit BasicScript Documentation directory on the RemoteWare CD. User s Guide/VirusScan for Windows 3.1, 95, and NT. Helps the Windows Client user understand the functionality in McAfee VirusScan for Windows 3.1, Windows 95, and Windows NT Workstation 4.0. pcanywhere. Assists you in using pcanywhere with RemoteWare Remote Control. Client guides RemoteWare 32-Bit Windows Client User s Guide. Helps the 32-bit Windows Client user install, set up, and understand the functionality in the RemoteWare Client. RemoteWare Windows 3.x Client User s Guide. Helps the 16-bit Client user install, learn, and take advantage of all the features available in the RemoteWare Windows 3.x Client software. RemoteWare OS/2 Client User s Guide. Presents the features, setup procedures, available options, and connection methods for the OS/2 Client software. RemoteWare Text-Based Clients User s Guide. Explains how to use the UNIX, VMS, 4690 and DOS Clients to communicate with the RemoteWare Server. RemoteWare Software Manager Client User s Guide. Describes how Client users can subscribe to Software Manager packages and then communicate with a RemoteWare Server to receive those packages.

16 xvi RemoteWare AntiVirus Manager Administrator s Guide Additional information sources There are several sources of information related to RemoteWare. They include the following: Online help. The RemoteWare online help provides easy access to information about each application s main functions. PDF documentation. The RemoteWare administrator and user guides are available as electronic documents on the RemoteWare CD-ROM. RemoteWare information on the web. For current RemoteWare information, visit XcelleNet s web site.

17 CHAPTER 1 1 Installing API Files This chapter lists the compiler requirements and provides instructions to install the RemoteWare API files. This chapter includes: Supported operating system environments Supported compilers Installing the API files from the RemoteWare CD-ROM Installing the Win32 COM Object Client APIs Test bed information Using the APIs with Visual Basic

18 18 RemoteWare API Manual Supported environments The RemoteWare APIs operate on any IBM PC compatible computer running the following: Table 2. Supported operating environments API Type Supported Operating System Server API 16-bit Windows Client API 32-bit OS/2 Client API OS/2 4.0 DOS Client API 32-bit Windows Client API Win32 COM Object Client APIs 32-bit Windows Client ActiveX Control Windows NT (version 4.0 with Service Pack 3 or later) Windows 3.1x (under MS-DOS 3.1 or later); Windows 95, Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) MS-DOS 5.0 or later Windows 95, Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) Windows 95 Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) Windows 95, Windows 98, or Windows NT (version 4.0 with Service Pack 3 or later) The compiler you use may have stricter system requirements than these. See your compiler documentation for details.

19 CHAPTER 1 / Installing API Files 19 Supported compilers The RemoteWare API supports the programming languages shown in the following table. Table 3. Supported compilers API Type Supported Compilers Server API Microsoft Visual C bit Windows Client API Microsoft Visual C Microsoft Visual Basic Professional 4.0 (16-bit) 32-bit OS/2 Client API IBM Visual Age 3.0 DOS Client API Microsoft Visual C bit Windows Client API Microsoft Visual C Microsoft Visual Basic Professional 4.0 (32-bit) Win32 COM Object Client APIs Microsoft Visual C Microsoft Visual Basic Professional 5.0 (32-bit) 32-bit Windows Client ActiveX Control Microsoft Visual C Microsoft Visual Basic Professional 5.0 (32-bit) You may be able to use other compilers and programming languages with the APIs, although XcelleNet has only tested the languages above. In addition, all examples in this manual demonstrate API functions with Microsoft C++.

20 20 RemoteWare API Manual Installing the API files from the CD-ROM All RemoteWare APIs except the Win32 COM Object Client APIs are installed when you install the RemoteWare Developer s Kit from the Server installation program on the RemoteWare CD. Follow the instructions in the RemoteWare Server Installation Guide to start the installation, then choose Developer s Kit from the Setup Menu. Follow the onscreen instructions. Copying API files If you want to work with specific APIs only, you can copy the appropriate files from the machine on which the RemoteWare Developer s Kit was installed. The table below shows the default directories in which the files are installed. If you changed the installation path during the RemoteWare Developer s Kit installation, substitute the new path for \rdk. Table 4. Directories for API families API Type 32-bit Windows Client ActiveX Control DOS Client API OS/2 Client API 16-bit Windows Client API 32-bit Windows Client API Server API Directory for C++ version \rdk\activex\ \rdk\client\dos\include\ \rdk\client\dos\lib\ \rdk\client\os2\include\ \rdk\client\os2\lib\ \rdk\client\win16\msvc152\include\ \rdk\client\win16\msvc152\lib\ \rdk\client\win32\msvc60\include\ \rdk\client\win32\msvc60\lib\ \rdk\server\include\ \rdk\server\lib\ To copy specific API files: 1 Create or designate a directory where you intend to develop your API programs. If you plan to develop multiple APIs on this computer (for example, both the Server and 32-bit Client APIs), create a separate directory on your hard drive for each API. 2 Copy the contents of the directories listed in Table 4 to the directories you created in step 1.

21 CHAPTER 1 / Installing API Files 21 Testing your API programs The computer where you test your API programs must have certain files installed. If you are testing programs that use RemoteWare Server APIs, you must install the DLLs where the operating system can find them. You must also run any programs that use the RemoteWare Server APIs from the Server s data drive. If you are testing programs that use the DOS Client APIs or 16- or 32-bit Windows Client APIs, you must have the corresponding RemoteWare Client software installed. All necessary DLLs and related files are installed when you install the Client software. You must also run your programs that use Client APIs from the Client s data drive. Using the APIs with Visual Basic All of the Client API functions described in this manual work with Visual Basic except the 16-bit Client s RWNObjectQueryInfo and RWNObjectQueryObjects functions. Note: You can ignore any references to #define statements in this manual when using Visual Basic.

22 22 RemoteWare API Manual

23 CHAPTER 2 2 Using the API Functions This chapter discusses issues and requirements for successfully using RemoteWare API functions. This chapter applies only to the APIs referenced in Chapters 3, 4, 5, 6, and 7. This chapter includes: Error handling Interpreting data types

24 24 RemoteWare API Manual Error handling Many RemoteWare API functions return an error code to indicate whether the function completed successfully. Your program should always check the return codes of any function that returns something other than void. Otherwise, your program may not function as expected. For example, suppose you create a program that starts a session on a particular RemoteWare Client using the RWSScheduleSession() API function. The session s worklist contains a NOTIFY command that signals your program when the session reaches a particular point. To wait for that signal, your program uses the API function RWSNotifyWait(). If a session could not be scheduled for some reason, the NOTIFY signal would never be issued. Therefore, if your program does not check the RWSScheduleSession() return code, your program would wait for a NOTIFY signal that never arrives and would seem to hang. Types of errors Generally, errors fall into two groups: recoverable errors and non-recoverable errors. It is your responsibility to decide which is which, although some errors (such as invalid parameters) indicate bugs in your program that are difficult to recover from while the program is running. For example, the RWSScheduleSession() function in the next example can return one of the error codes listed in the following table. Table 5. Error types Error code 0 (zero) The function was successful E_RWS_PARAM E_RWS_NOCLIENTS E_RWS_DISABLED E_RWS_SCHED other Invalid calling parameter No Clients are assigned to the group specified, or no Clients are assigned to the session if RWS_ALL_ASSIGNED was specified. The specified session or the specified individual Client is disabled. The session was not successfully submitted to the scheduler. A Windows NT error occurred. This value indicates the WIN32 error code. A simple error handler could print an error message and terminate if the return code is something other than zero. An elaborate handler might automatically attempt to correct any error condition. The following code provides an in-between approach to handling return codes. In the example, the function MyAlert() displays a message explaining the problem and asking the user whether to retry the function or abort the program.

25 CHAPTER 2 / Using the API Functions 25 short error; USHORT status; char from_client[namelgt]; /*... */ /* start the session */ status = RWSScheduleSession( DailyUpdate", "ATLANTA", RWS_NOW ); switch( status ) case 0: /* no problem */ done = TRUE; break; case E_RWS_PARAM: /* invalid parameter */ printf( internal error... exiting\n ); terminate(); break; // E_RWS_NOCLIENTS will not come up since we are only // working with a single client instead of a group or // all assigned clients. case E_RWS_DISABLED: /* session or client disabled */ done = MyAlert( Session or client disabled. ); break; case E_RWS_SCHED: /* session not scheduled */ done = MyAlert( Session not scheduled. ); break; default: /* WIN32 error */ printf( WIN32 error: %d\n, status ); terminate(); break; RWSNotifyWait( MyQueue, from_client, &error );

26 26 RemoteWare API Manual Interpreting data types The following table lists the data types used for the functions and parameters described in Chapters 3, 4, 5, and 6. Table 6. Data types Data Type BOOL BYTE char, CHAR FAR INT LONG PASCAL PRWHANDLE PSZ PUSHORT short, SHORT ULONG unsigned unsigned short USHORT void WORD Unsigned integer (32-bit in WIN32, 16-bit in all other operating systems). 8-bit unsigned character. 8-bit signed character. (Windows 3.1x and DOS only.) Defines a data pointer or function consisting of a 16-bit segment address and a 16-bit offset address. Signed integer (32-bit in WIN32, 16-bit in all other operating systems). 32-bit signed integer. (Windows 3.1x and DOS only.) Defines a function using the Pascal naming conventions (the function name becomes all uppercase with no prepended underscore) and parameter-passing conventions. Pointer to a variable of type RWHANDLE. RWHANDLE is a WIN32 HANDLE type. Pointer to a C string, which is a NULL-terminated (zero-terminated) data string. Pointer to USHORT. 16-bit signed integer. 32-bit unsigned integer. Unsigned integer (32-bit in WIN32; 16-bit in all other operating systems). 16-bit unsigned integer. 16-bit unsigned integer. Indicates a C function with no return value; also used in function prototypes. 16-bit unsigned integer.

27 CHAPTER 3 3 Server API Functions This chapter covers the Server API functions that run on the RemoteWare Server, including how to use the functions and interpret their return codes. It also presents the functions, their parameters, relevant comments, and examples. This chapter includes: General notes on using Server API functions New Server API functions Building Server applications Server API error codes Server Alarm API functions Server Worklist API functions Server Notify API functions Server Database API functions Server Object API functions Server Schedule API functions

28 28 RemoteWare API Manual General notes To use the RemoteWare Server API functions, your program should contain an #include <windows.h> followed by an #include <rwsapi.h>. To use Worklist or Object (work object) API functions, link with RWSRUNTM.LIB, and run with RWSRUNTM.DLL in your path. To use all other functions, link with RWSAPI.LIB, and run with RWSAPI.DLL in your path. When including RWSAPI.H, be sure to #define INCL_RWS_WORKLIST if your program uses the worklist APIs. The portion of the header file containing the worklist constants, structures, and prototypes is conditionally included. As always, programs using the RemoteWare for Windows NT Server APIs must run on the Server s data drive. New functions The Worklist API functions have been restructured compared to previous RemoteWare versions earlier than version RWSResetSecurity() resets the fourth level of Client security on a RemoteWare Server. RWSWorklistAction() no longer exists. It is replaced by the separate RWS functions described below. RWSGetNumberofRecords() determines the number of records in a worklist file. RWSReadWorklistRecord() reads a specified number of records from an open worklist file. RWSWriteWorklistRecord() writes a specified number of records to an open worklist file. RWSDeleteWorklistRecord() deletes a worklist record at a specified offset from the first record in an open worklist file. RWSAppendWorklistRecord() appends a worklist record at the end of an open worklist file. RWSWorklistSave() saves an open worklist file. RWSWorklistClose() more easily closes a worklist file handle using a single parameter. RWSWorklistOpen() remains unchanged.

29 CHAPTER 3 / Server API Functions 29 Building Server applications To build an application using the RemoteWare APIs, simply include the RWSRUNTM.LIB and RWSAPI.LIB files in your project. If the application you build do not behave the same, check the following: Verify you are using the correct version of your compiler. For example, confirm you are not building 32-bit code with a 16 bit compiler. Confirm you have the correct set of include files and libraries for your environment. You may have to generate an import library. See your compiler manual for more information on how to create import libraries from a DLL without object files or source.

30 30 RemoteWare API Manual Error codes The RemoteWare Server APIs generally return two types of error codes. A positive error code is likely a WIN32 error that you can look up in most Windows NT technical references. A negative error is probably specific to RemoteWare. The following table shows a list of all the error codes defined for the RemoteWare Server. The description of each function also lists the error codes that may be returned by that function. Table 7. Server API error codes Name E_RWS_EOF E_RWS_PARAM E_RWS_NOCLIENTS E_RWS_DISABLED E_RWS_SCHED E_RWS_EXISTS E_RWS_NOT_EXISTS E_RWS_MAX E_RWS_INCOMPLETE E_RWS_INVALID_KEY E_RWS_INVALID_OWNER E_RWS_MSG_LOGGED E_RWS_LOW_MEMORY E_RWS_NOAPPREGFILE E_RWS_IN_USE E_RWS_NO_RENDEL E_RWS_UNDEFINED E_RWS_FAILED E_RWS_CONFLICT E_RWS_AUTOASN_FAILED End of file reached. Invalid parameter supplied. No Clients are assigned. The specified session or Client was disabled. Submit session failed. Specified name already exists. Specified name does not exist. Maximum number of objects already created. Object was created but not all information was successfully associated with the object. Invalid key specified. The owner of the group does not match the owner of the object. API logs a message to the Server Log if an error occurred while modifying the assignments. Insufficient memory available to perform the requested operation. Application registration file could not be found Item is being edited elsewhere. Object cannot be renamed or deleted because of its assignment to a group Unknown error occurred. General failure occurred Conflicting assignment exists. Autoassign attempt caused a conflicting assignment, so the autoassign was not completed.

31 CHAPTER 3 / Server API Functions 31 Server Alarm API functions Alarm API functions let you check the status of RemoteWare for Windows NT Server alarms, set alarms under program control, or clear (delete) alarms. The RWSAPI.DLL file contains these functions. You must execute programs using these functions on the Server s data drive. Uses for these functions include: Monitoring certain alarms and taking appropriate action Setting alarms, for example, to indicate an error detected by your program Passing RemoteWare alarms to a network management system Valid Alarm API functions and alarm types for the RemoteWare Server include: Table 8. Server Alarm API functions Function Name RWSIsAlarmSet RWSGetAlarmText RWSSetUserAlarm RWSClearAlarm Check the status of the specified alarm. Get the alarm message text for the last occurrence of the alarm. Set the User alarm and log message text associated with the alarm. Clears an alarm that is currently set. Table 9. Alarm API types Alarm Type ALARM_SERVER_REBOOT ALARM_SCHEDULER_LOADING ALARM_SCHEDULER_OFF ALARM_SCHEDULER_OVERRUN ALARM_SERVER_DISK_FULL ALARM_CLIENT_DISK_FULL ALARM_LOW_MEMORY ALARM_FATAL_ERROR ALARM_PORT_FAILURE ALARM_XSUPPORT ALARM_SERVER_DOWN ALARM_SCHEDULER_FULL ALARM_USER_DEFINED ALARM_MODEM_ERROR The Server was rebooted. The Loader is still running. The Scheduler is disabled. A session is out of range. The Server disk is full. A Client disk is full. The Server is low on memory. A System Fatal Error was detected. The COM port has excessive errors. Support Response was received. A Clustered Server is down. All Scheduler queues are full. User-defined alarm or User Alarm. The Server modem has generated an error.

32 32 RemoteWare API Manual Alarm Type ALARM_SERVER_SUSPENDED ALARM_SECURITY_FAILURE ALARM_MANUAL_CLIENTREG ALARM_MTA_FAILURE The Server is in a suspended state. A Sentinel security failure was detected. Manual verification of a Client s registration information is required. Mail Transfer Agent failure occurred. Internally, alarm types are integers from 0 (zero) to TOTAL_ALARMS-1, where TOTAL_ALARMS is a symbolic constant defined in RWSAPI.H. Server Alarm API RWSIsAlarmSet Applicable Alarm Types C Synopsis Parameters ialarm Return values True False This function returns the status of the specified alarm (i.e., whether the alarm is set or cleared). All. For information on Alarm Types, see Server Alarm API functions on page 31. BOOL RWSIsAlarmSet( SHORT ialarm ); This parameter specifies the alarm type that you want to test. For a list of valid Alarm Types, see Server Alarm API functions on page 31. This function returns one of the following values: The alarm is set. The alarm is cleared. Example if( RWSIsAlarmSet(ALARM_SERVER_DISK_FULL) ) printf( Server disk is full.\n ); exit();

33 CHAPTER 3 / Server API Functions 33 Server Alarm API RWSGetAlarmText Applicable Alarm Types This function returns the alarm message text for the last occurrence of the specified alarm. RWSGetAlarmText() is valid only for the following alarm types: ALARM_CLIENT_DISK_FULL ALARM_PORT_FAILURE ALARM_MODEM_ERROR ALARM_USER_DEFINED ALARM_FATAL_ERROR ALARM_SERVER_DOWN ALARM_MTA_FAILURE ALARM_MANUAL_CLIENTREG For information on Alarm Types, see Server Alarm API functions on page 31. C Synopsis Parameters ialarm psztext Return values True False Example BOOL RWSGetAlarmText( SHORT ialarm, PSZ psztext ); This parameter specifies the alarm type for which you are requesting message text. Only the alarm types listed at the beginning of this RWSGetAlarmText() description provide message text. The other alarm types are invalid for this function. On entry, you pass a text pointer to a buffer of ALARM_TEXT_SIZE+1 bytes (ALARM_TEXT_SIZE is a symbolic constant defined in RWSAPI.H). If the function returns successfully, this buffer contains the null-terminated error text. This function returns one of the following values: The function completed successfully. The supplied Alarm type (ialarm) was invalid. char AlarmText[ALARM_TEXT_SIZE+1]; if ( RWSIsAlarmSet(ALARM_USER_DEFINED) ) RWSGetAlarmText( ALARM_USER_DEFINED, AlarmText ); printf( User alarm: %s\n, AlarmText );

34 34 RemoteWare API Manual Server Alarm API RWSSetUserAlarm Applicable Alarm Types C Synopsis Parameters psztext This function sets the User alarm and logs associated message text to the Server s Message Log. ALARM_USER_DEFINED For information on Alarm Types, see Server Alarm API functions on page 31. VOID RWSSetUserAlarm( PSZ psztext ); A pointer to a null-terminated string containing the error text you want to assign to the user alarm. This text appears in the Server s Message Log. The string can be up to ALARM_TEXT_SIZE bytes, plus a null terminator (ALARM_TEXT_SIZE is a symbolic constant defined in RWSAPI.H). If you exceed this length, the Server will truncate the string to this size. Return values None Example RWSSetUserAlarm( This text explains the alarm ); Server Alarm API RWSClearAlarm Applicable Alarm Types This function clears the specified alarm, if it is set. Use this function to clear RemoteWare for Windows NT Server alarms after you have corrected the condition that caused the alarm. ALARM_SERVER_REBOOT ALARM_SCHEDULER_OVERRUN ALARM_CLIENT_DISK_FULL ALARM_FATAL_ERROR ALARM_PORT_FAILURE ALARM_USER_DEFINED ALARM_MODEM_ERROR ALARM_MTA_FAILURE ALARM_MANUAL_CLIENTREG For information on Alarm Types, see Server Alarm API functions on page 31.

35 CHAPTER 3 / Server API Functions 35 Server Alarm API RWSClearAlarm (Continued) C Synopsis Parameters ialarm Return values True False BOOL RWSClearAlarm( SHORT ialarm ); This parameter specifies the alarm type that you want to clear. Only the alarm types listed at the beginning of this RWSGetAlarmText() description provide message text; the other alarm types are invalid for this function. This function returns one of the following values: The alarm was cleared successfully. Either the alarm was not set or you supplied an invalid alarm type. Example RWSClearAlarm( ALARM_USER_DEFINED ); Server worklist API functions Worklist API functions may be used to create and manipulate a list of events just as an operator would in the Work Object Editor on the RemoteWare Server. The RWSRUNTM.DLL file contains the Worklist API functions. Any programs that use these functions must be executed on the Server s data drive. Your programs can use these APIs to perform tasks or modify existing units of work on the Server. For a more detailed description of worklists and related issues, see Worklist Events on page 175. The following table lists the RemoteWare Server Worklist API functions. Uses for these functions include: Retrieving a Client s directory listing Building a list of Client files to be collected by the Server Commanding a Client to run an executable program Synchronizing a Client and the Server s system clock

36 36 RemoteWare API Manual Function Name RWSWorklistOpen RWSWorklistClose RWSWorklistSave RWSGetNumberOfRecords RWSReadWorklistRecord RWSWriteWorklistRecord RWSDeleteWorklistRecord RWSAppendWorklistRecord Opens a worklist file for further actions using other Worklist API functions. Closes a worklist file handle. Saves an open worklist file. Determines the number of records in a specified open worklist file handle. Reads a specified number of records from an open worklist file. Writes a specified number of records to an open worklist file. Deletes a worklist record at a specified offset from the first record in an open worklist file. Appends a worklist record at the end of an open worklist file. Server Worklist API RWSWorklistOpen RWSWorklistOpen() opens a worklist file and loads it into a buffer for further operations by other Worklist API functions. All operations (Read/Write/Delete) are performed on this buffer. The buffer is saved to disk using RWSWorklistSave(), which writes the buffer to disk but keeps the worklist handle open. RWSWorklistClose() closes the worklist handle. C Synopsis Parameters phworklist pszworklistfile Return values INT RWSWorklistOpen( PRWHANDLE phworklist, LPCSTR pszworklistfile ); This is a pointer to a variable of type RWHANDLE, which receives the file handle upon successful opening of the worklist file. This is a pointer to a null-terminated string that specifies the worklist file s name. Worklist filenames typically take the form \\WORKLIST\\<filename>.EVF. This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs.

37 CHAPTER 3 / Server API Functions 37 Server Worklist API RWSWorklistOpen (Continued) Example RWHANDLE fhworklisthandle; INT rc; rc = RWSWorklistOpen( &fhworklisthandle, test.evf ); if ( rc ) printf( RWSWorklistOpen: error %d\n, rc ); else puts( RWSWorklistOpen:OK ); Server Worklist API RWSWorklistClose C Synopsis Parameters hworklist Return values This function closes a worklist file handle that was opened using RWSWorklistOpen(), but does not save the file. INT RWSWorklistClose( RWHANDLEhWorklist ); This variable initially received the file handle from the call to RWSWorklistOpen() and identifies the Worklist file to be closed. This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs. Example RWHANDLE fhworklisthandle; INT rc; rc = RWSWorklistClose( fhworklisthandle ); if ( rc ) printf( RWSWorklistClose: error %d\n, rc ); else puts( RWSWorklistClose: OK );

38 38 RemoteWare API Manual Server Worklist API RWSWorklistSave C Synopsis Parameters hworklist Return values This function saves a worklist file that was opened using RWSWorklistOpen(), but does not close the file handle. NT RWSWorklistSave( RWHANDLE hworklist ); This variable initially received the file handle from the call to RWSWorklistOpen() and identifies the Worklist file to be saved. This function returns 0 (zero) if successful, or an WIN32 error code if an error occurs. Example RWHANDLE fhworklisthandle; INT rc; rc = RWSWorklistSave( fhworklisthandle ); if ( rc ) printf( RWSWorklistSave: error %d\n, rc ); else puts( RWSWorklistSave: OK ); Server Worklist API RWSGetNumberOfRecords C Synopsis Parameters hworklist Return values This function returns the number of records contained in a specified worklist handle, which was opened using RWSWorklistOpen(). INT RWSGetNumberOfRecords( RWHANDLE hworklist ); This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file for which the record count is needed. This function returns the number of records contained in the specified open worklist file handle.

39 CHAPTER 3 / Server API Functions 39 Server Worklist API RWSGetNumberOfRecords (Continued) Example RWHANDLE fhworklisthandle; UINT uicount; uicount = RWSGetNumberOfRecords ( fhworklisthandle ); printf( RWSGetNumberOfRecords returned %d\n, uicount ); Server Worklist API RWSReadWorklistRecord C Synopsis Parameters hworklist pworklistrec puireadcount This function reads a specified number of records from a worklist file handle that was opened by RWSWorklistOpen(). The record number from which to start reading is specified in the irecordnumber member of the RWWORKLIST structure that is passed to RWSReadWorklistRecord(). INT RWSReadWorklistRecord( RWHANDLE hworklist, PRWWORKLIST pworklistrec, PUINT puireadcount ); This variable contains the file handle provided by RWSWorklistOpen() and specifies the particular Worklist file that should be read. This is a pointer to a variable or array of variables of type RWWORKLIST (described later in this section) that will receive the record(s) to be read. The record number from which to start reading must be specified in the irecordnumber member of this structure (only in the first element of an RWWORKLIST array). If an array is used, the number of array elements should equal the value of puireadcount (see the next parameter). This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to read. On return, the integer contains the number of records actually read.

40 40 RemoteWare API Manual Server Worklist API RWSReadWorklistRecord (Continued) RWWORKLIST Structure of RWWORKLIST cb irecordnumber The RWWORKLIST parameter is used as described in the pworklist Rec parameter above. The RWWORKLIST parameter is also used in the RWSReadWorklistRecord(), RWSWriteWorklistRecord(), and RWSAppendWorklistRecord() functions. typedef struct _RWWORKLIST USHORT cb; SHORT irecordnumber; SHORT scommand; BYTE bwhere; BYTE bwhen; ULONG uloptions; LONG lusercontext; USHORT usreferencecount; CHAR szparam1[max_param_length]; CHAR szparam2[max_param_length]; BYTE Reserved[36]; RWWORKLIST, *PRWWORKLIST; This is the size of this RWWORKLIST record. This is the worklist record number from which to start reading or writing records (depending on whether the RWSReadWorklistRecord() or RWSWriteWorklistRecord() function is called). A value is not required for the RWSAppendWorklistRecord() function.

41 CHAPTER 3 / Server API Functions 41 Server Worklist API RWSReadWorklistRecord (Continued) scommand This is a worklist command. Valid command values WL_SENDFILE Send a file to the Client. WL_GETFILE Get a file from the Client. WL_SENDDIR Send a directory to the Client. WL_GETDIR Get a directory from the Client. Note: The WL_SENDDIR and WL_GETDIR events are provided for backward compatibility only. For new applications, use the WL_SENDFILE and WL_GETFILE events with wildcards instead. WL_RENAMEFILE Rename a file. WL_DELETEFILE Delete a file. WL_COPYFILE Copy a file. WL_APPENDFILE Append one file to another. WL_FILESTAT Check if file exists. WL_DIRECTORY Pipe directory listing to a file. WL_CHECKDISK Check disk statistics. WL_MAKEDIR Make a directory.

42 42 RemoteWare API Manual Server Worklist API RWSReadWorklistRecord (Continued) scommand Valid command values (continued) WL_REMOVEDIR Remove a directory. WL_SETTIME Set Client time. WL_EXECUTE Execute another program. WL_WORKLIST Insert a worklist. WL_NOTIFY Notify another process. WL_REBOOT_CLIENT Reboot Client at end of session. WL_WAIT Wait for file or timeout. WL_ASCII_APPEND Append ASCII file with ^Z check. WL_USER_ALARM Set user alarm and message. WL_END_SESSION End session gracefully. WL_IF_TRUE If previous event is true then... WL_IF_FALSE If previous event is false then... WL_ELSE_IF Else do the following... WL_END_IF End of IF block. WL_REPEAT_IF_TRUE Repeat if previous event true.

43 CHAPTER 3 / Server API Functions 43 Server Worklist API RWSReadWorklistRecord (Continued) scommand Valid command values (continued) WL_REPEAT_IF_FALSE Repeat if previous event false. WL_END_REPEAT End repeat block. WL_EXCEPTION Exception worklist. WL_GROUP_TEST Test if Client is in specific group. WL_COMMENT Add comment text. WL_SET_VARIABLE Set environment variable s value. WL_TEST_VARIABLE Test environment variable. WL_CHECK_FILE Check file date/time/size. bwhere This parameter specifies where the worklist command should be executed. Valid command values WL_ON_SERVER The command runs on the Server. WL_ON_CLIENT The command runs on the Client. Note: Some commands run only on the Server; others run only on the Client. The function does not verify that the location is valid for the command you specify.

44 44 RemoteWare API Manual Server Worklist API RWSReadWorklistRecord (Continued) bwhen This parameter specifies when the worklist command is executed. Valid command values WL_BEFORE Execute before communication session. WL_DURING Execute during communication session. WL_AFTER Execute after communication session. Note: Some commands do not support all three possible bwhen values. The function does not verify that the bwhen value is valid for the command you specify. uloptions This bit mask specifies one or more options for this worklist command. Valid command values WL_NO_OVERWRITE Do not overwrite an existing file. WL_UPDATEFILE Send only if file has different date, time, or size. WL_SAFE_SEND Send using temporary files. WL_CRITICAL Critical event. WL_DELETE_AFTER Delete file if successful. WL_CRITICAL_RETRY Critical event with retries. WL_NO_COMPRESS Do not apply compression. WL_NOT_NEEDED Not required for successful completion.

45 CHAPTER 3 / Server API Functions 45 Server Worklist API RWSReadWorklistRecord (Continued) uloptions (Continued) WL_CONDITIONAL_FALSE Conditional execute if FALSE. WL_SEND_NEWER Update only if file is newer. WL_COMPARE_EQUAL Executes if equal. WL_COMPARE_GREATER Executes if greater than. WL_COMPARE_GREATEREQ Executes if great than or equal to. WL_COMPARE_LESS Executes if less than. WL_COMPARE_LESSEG Executes if less than or equal to. WL_COMPARE_NOT EQ Executes if no equal. WL_PREVIOUS_FALSE Executes if previous event false. WL_PREVIOUS_TRUE Executes if previous event true. szparam1, szparam2 These two members hold parameters (each of size MAX_PARAM_LENGTH) that are passed with the worklist command. For example, in the WL_SENDFILE and WL_GETFILE commands, these parameters specify the source and destination filenames. Reserved Return values This area is reserved for future use. The function returns TRUE if successful, or FALSE otherwise.

46 46 RemoteWare API Manual Server Worklist API RWSReadWorklistRecord (Continued) Example RWHANDLE fhworklisthandle; RWWORKLIST worklistrec; UINT uicount; INT rc; worklistrec.cb = sizeof( worklistrec ); // the following specifies which record in the open // worklist file we wish to begin reading from: worklistrec.irecordnumber = 0; uicount = 1; // read one record rc = RWSReadWorklistRecord( fhworklisthandle, &worklistrec, &uicount ); if (!rc ) printf( RWSReadWorklistRecord: error!\n ); else printf( RWSReadWorklistRecord: OK, read %d recs\n, uicount );

47 CHAPTER 3 / Server API Functions 47 Server Worklist API RWSWriteWorklistRecord C Synopsis Parameters hworklist pworklistrec puiwritecount Return values This function writes a specified number of records to a worklist file handle that was opened by RWSWorklistOpen(). The record number from which to start writing is specified in the irecordnumber member of the RWWORKLIST structure that is passed to RWSWriteWorklistRecord(). INT RWSWriteWorklistRecord( RWHANDLE hworklist, PRWWORKLIST pworklistrec, PUINT puiwritecount ); This variable contains the file handle that was provided by RWSWorklistOpen() and specifies the particular Worklist file that should be written. This is a pointer to a variable or array of variables of type RWWORKLIST that contain the record(s) to be written. (For a description of the RWWORKLIST structure, see RWSReadWorklistRecord on page 39.) The record number from which to start writing must be specified in the irecordnumber member of this structure (only in the first element of an RWWORKLIST array). If an array is used, the number of array elements should equal the value of puireadcount (see the next parameter). This is a pointer to an unsigned integer. On entry, the integer should be the number of records you wish to write. On return, the integer contains the number of records actually written. The function returns TRUE if successful, or FALSE otherwise. Example RWHANDLE fhworklisthandle; RWWORKLIST worklistrec; UINT uicount; INT rc; worklistrec.cb = sizeof( worklistrec ); // the following specifies which record in the open // worklist file we wish to write to. In this // case, we wish to write to the first record, // record 0: