Copyright: Actuate Software Corporation


  Report Server API

The Actuate Report Server Application Programming Interface Guide provides information about an API to control the Actuate Report Server. The Report Server API contains functions for performing tasks including:

•	Managing Report Objects in the Report Encyclopedia

•	Administering privileges, users, roles, and groups

•	Scheduling and controlling report generation and report printing

•	Implementing new feature groupings for custom business processes

Actuate Report Server API Guide includes the following sections.

Getting started with the Report Server API. This section provides a description of the development environment, an explanation of how to use the sample Report Server application, and shows how to create a minimal Report Server application.

Using the Report Server API. This section explains how to perform common reporting tasks from the API and describes how to handle server errors. A Visual C++ example shows how to perform a series of basic tasks.

Report Server API architecture. This section describes the Report Sever class hierarchy, software components, and object properties.

Report Server API reference. This section provides an alphabetical reference that describes the classes and member functions for the Report Server API.

See also

When to use the Report Server API


When to use the Report Server API

The Report Server API is a powerful interface for accessing the Report Server functionality. Use the Report Server API if you are developing an application with these requirements:

Environment—varied platforms and operating systems

Feature set—full Report Server functionality

Development resources—long design cycle that allows a learning curve

Using the Report Server API, you can integrate the Actuate reporting features into your existing applications and automate high-volume or routine reporting tasks.


Getting started with the Report Server API

This section describes the development environment for writing applications with the Report Server API and explains the sample program distributed with Actuate, egclient.

See also

Accessing the API
Referring to files--Windows environment
About egclient
Building egclient
Running egclient
Writing a minimal application
Building and running the minimal application


Accessing the API

The Report Server API is written in C++ and includes library, header, and executable files shipped with Actuate. At run time, your application accesses the API through a DLL interface.

See also

Compiler requirements
Setting up the development environment
For Microsoft Windows NT and 95:
Compiler settings for Visual C++ 4.x
DLL files
API file versions
Unix libraries and path variables
Compiler settings for Solaris 2.x, AIX, HP-UX


Compiler requirements

You need one of the following compilers to build an application using the Report Server API:

•	Windows NT and 95-- Visual C++ 4.1, 4.2, or 5.0

•	IBM AIX 4.2.0 -- C++ version 3.x

•	HP-UX 10.20-- HP ANSI C++ compiler if used with Actuate 3.1 or higher
                            The C-front compiler is not supported.
                       -- C++ A.10.24 to A.10.28 compiler, not ANSI C-C++
                         compiler, if used with Actuate 3.0

•	Solaris 2.5.1, 2.6-- SC4.2 C++


Setting up the development environment

Set up your environment to work with the Actuate Report Server API classes:

•	Include the file acrsapi.h. This file is in the include directory and is the only file needed for the Report Server API.

•	Install Rogue Wave Tools.h++ Foundation Classes. See DLLs for Windows environment, to find the correct version for your system. The header files in addition to the Server distribution are required. Tools.h++ is shipped with the Actuate Server distribution.

Call RogueWave Software for more information about Rogue Wave Foundation Classes.


For Microsoft Windows NT and 95:

•	The stdafx.h file--If you are including the stdafx.h file in your application, include it before acrsapi.h.

•	PATH environment variable--After you build your application and it is ready to execute, either:

•	Set your Windows environment variable PATH to include the Report Server API lib directory to look for DLLs. For example, set path=%path%;e:\actuate\sdk\rsapi\nt\lib

or:

•	Copy all the DLLs from the LIB directory to your standard DLL installation directory.


Compiler settings for Visual C++ 4.x

Make the following settings:

•	Path to include files--Add the Report Server API and Rogue Wave include path to your environment. For example, if the Report Server API is installed in e:\actuate\sdk\rsapi, set your include path to e:\actuate\sdk\rsapi\include.

•	Path to libraries--Add the Report Server API and Rogue Wave library path to your environment. For example, if the Report Server API is installed in e:\actuate\sdk\rsapi, set your library path to e:\actuate\sdk\rsapi\lib.

•	Click Build→Settings. From the C/C++ tab, define the pre-processing macros "_RWTOOLSDLL" and "_ACRSDLL" .

•	Set the Category to Code Generation and, if necessary, set Use Run-Time Library to Multithreaded DLL.

•	If you are using Report Server API DLLs, link the following libraries with your application: and the ACR, ACRQ, and ACRS libraries and DLLs listed in the next section:


DLL files

The Report Server API utilizes DLL files during execution. Actuate periodically updates these files to enhance features, correct problems, and support different development environments. This section explains how to choose the correct files for your application.

See also

API file name conventions
DLLs for Windows environment


API file name conventions

The following table summarizes the naming conventions for files used by the Report Server API

DLL	File Name
Report Server API DLL	ACRSxxyy.DLL • xx = Report Server API version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACRS3041.DLL
RogueWave DLL	ACRxxyy.DLL • xx = RogueWave version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACR7042.DLL
Requester API DLL	ACRQxxyy.DLL • xx = Report Server API version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACRQ3041.DLL
.


API file versions

When choosing the correct API file for your application, follow these guidelines:

•	Always use the WINRPC32.LIB

•	Use the LIB files that correspond to the DLLs for the release you are using.

•	Choose the LIB and DLL files compiled for the VC++ version you are using.

•	Refer to the release notes for the most up-to-date information on DLL or LIB files.


DLLs for Windows environment

When linking your Windows application, specify the library files appropriate for your compiler and Actuate release using the following table, which summarizes the DLL files for each Actuate release, according to your compiler version:

Release	VC++ 4.1	VC++ 4.2	VC++ 5.0
3.2	See release notes	See release notes	See release notes
3.1 and 3.1.1	ACRS3341.DLL ACR7041.DLL ACRQ3341.DLL	ACRS3342.DLL ACR7042.DLL ACRQ3342.DLL	ACRS3350.DLL ACR7050.DLL
3.0.6	ACRS3241.DLL ACR7041.DLL ACRQ3041.DLL	N/A	N/A
3.0.5	ACRS3241.DLL ACR7041.DLL ACRQ3041.DLL	N/A	N/A
3.0.4	ACRS3141.DLL ACR7041.DLL ACRQ3041.DLL	N/A	N/A
3.0.0 - 3.0.3	ACRS3041.DLL ACR7041.DLL ACRQ3041.DLL	N/A	N/A


Unix libraries and path variables

When linking your UNIX application, set the library path to the shared library and the path to the include files for your specific UNIX system. Make sure the environment variable AC_SERVER_HOME is properly set for the server installation on your UNIX system.


Compiler settings for Solaris 2.x, AIX, HP-UX

•	Link the Report Server API libraries. For a list of libraries supported for your operating system, see make.include in the rsapi examples directory.

•	To build the example program, go to the examples directory for a specific OS, edit the Makefile, and specify proper path names for the following macros:

	Macro	Description
	APILIBDIR	Report Server API library directory
	APIINCDIR	Report Server API include directory
	RWLIBDIR	Rogue Wave library directory
	RWINCDIR	Rogue Wave include directory
•	Execute the command: make

The egclient executable is placed in the examples directory.

•	To use egclient, set the following environment variable:

setenv LD_LIBRARY_PATH $APILIBDIR

APILIBDIR is the parent directory in which the Actuate Report Server API is installed.


Referring to files--Windows environment

This section describes how to enter file names on the egclient command line and to create file name strings that the API understands.

See also

In the source code
On the egclient command line


In the source code

Strings in the source code containing the path and name of the report item in the Windows file system take double backslashes. The first backslash is the escape character.

sourceFile = "D:\\Actuate\\Devwb\\Examples\\Forecast\\forecast.rov";

Strings in the source code specifying the printer in the Windows environment also take double backslashes.

RWCollectableString printerName = "\\\\lahaina\\HP LASERJET IIP";

Strings in the source code containing the path and name of the report item in the Report Encyclopedia are written with a single forward slash.

destFile = "/Western Region/forecast.rov";

destFile = "rotp://MyServer/Western Regions/forecast.rov;3";

For more information, see Specifying report server file names--Requester API in


On the egclient command line

To run egclient from the DOS command line:

Enter paths and filenames to report items with quotation marks around their path if they have embedded spaces. Use the forward slash as the file separator for the Report Encyclopedia and the backslash as the separator for the local Windows file system.

For example, the egclient code entitled reportObject test 7 reads an object from the Report Encyclopedia to the file system or vice versa. Entering the first parameter with the -1 switch identifies the source file with quotes in the Report Encyclopedia folder, Eastern Region. Entering the second parameter with the -2 switch identifies the destination file without quotes in C:\Temp, as shown by the following example:

C:\API Examples>egclientD -CreportObject -T7 -1"/Eastern Region/forecast.rox" -2C:\Temp\forecast.rox -Mhaleakala -UAdministrator


About egclient

Exercising egclient in the examples directory is the best way to learn about the Report Server API.

See also

Egclient functional overview


Egclient functional overview

The following table describes each of the tests in egclient, important classes used in these tests, and the name and number of the tests. The information in the key classes and functions column does not necessarily list every class used in the test, and the classes are not listed in any particular order in relationship to the tests listed in the test name column.

Test description	Key classes & functions	Test name
Add and delete users from Report Encyclopedia.	AcAddUser, AcDeleteUser	userTable 2, 3
Add and delete roles from users.	AcAddRoleToUser, AcDeleteRoleFromRole	userTable 4, 5
Set user preferences.	AcSetUserPreferences	userTable 6
Access user names, roles, and preferences.	AcGetUserNames, AcGetUserData	userTable 7, 8
Create and add or delete groups from the encyclopedia.	AcAddUserToGroup, AcAddGroup, AcDeleteGroup	groupTable 1, 2, 4
Access group names.	AcGetGroupNames, AcGetGroupUserNames	groupTable 3, 5
Add channel.	AcAddChannel	channelTable 1
Delete channel.	AcDeleteChannel	channelTable 2
Identify available channels.	AcGetChannelNames	channelTable 3
Establish channel preferences.	AcSetChannelProperties	channelTable 4
Access channel preferences.	AcGetChannelProperties	channelTable 5
Add user privileges to channel.	AcAddPrivilegeToUser	channelTable 6
Add role privileges to channel.	AcAddPrivilegeToRole	channelTable 7
Delete user privileges from channel.	AcDeletePrivilegeFromUser	channelTable 8
Delete role privileges to the channel.	AcDeletePrivilegeFromRole	channelTable 9
Dump the table of channel information.	AcGetChannelNames, AcGetChannelProperties, AcGetUserNames, AcGetRoleNames	channelTable 10
Dump a table data on roles.	AcGetRoleNames	roleTable 1
Add and delete roles.	AcAddRole, AcDeleteRole	roleTable 2 and roleTable 3
Get users with a given role.	AcGetUsersWithRole	roleTable 4
Add a role to a role	AcAddRoleToRole	roleTable 5
Get the roles inherted by a role.	AcGetRolesOfRole	roleTable 6
Get server management information: report item owner, size, and date of creation.	AcPersistentObject::GetTree	reportObject 1
List encyclopedia folder contents.	AcPersistentObject::GetName, AcPersistentObject::GetType, AcPersistentObject::GetVersionNumber,  AcPersistentObject::GetID	reportObject 2
Add and delete a report item from the encyclopedia.	AcPersistentObject	reportObject 3, 4
Access report items properties, ID, owner, size, modification date, dependents, dependencies.	AcPersistentObject	reportObject 5
Create a directory in the encyclopedia.	AcPersistentObject	reportObject 6
Read bytes from one object into another.	AcPersistentObject	reportObject 7
Read element.	AcPersistentObject::ReadToLocalFile	reportObject 8
List elements of an ROX.	AcPersistentObject::GetElements	reportObject 10
Determine how many users are logged in.	AcGetNumberOfUserLogins	requestObject 1
Access logged-in users.	AcGetLoginUsers	requestObject 2
Get the completed requests for a given user, or the administrator by default.	AcGetUserCompletedRequests	requestObject 3
Identify requests completed for the Report Encyclopedia item.	AcGetObjectCompletedRequests	requestObject 4
Get pending requests for a user.	AcGetUserPendingRequests	requestObject 5
Get scheduled requests for a user.	AcGetUserScheduleRequests	requestObject 6
Access information about a request, such as the IDs of associated objects.	AcGetRequestInformation	requestObject 7
Delete completed request information and determine if request is scheduled.	AcDeleteRequestStatusInformation, AcGetServerTime, AcGetRequestInformation	requestObject 8
Delete active requests, which include scheduled requests that are running.	AcDeleteRequest	requestObject 9
Run a request now.	AcExecuteObject	requestObject 10
Schedule a request to run later.	AcExecuteObject, AcSchedule	requestObject 11
Schedule a request to run with top priority.	AcExecuteObject	requestObject 12
Delete a specific version of the same ID, which is done when completed requests are generated from a schedule request, because all the completed requests have the same ID but different versions.	AcGetRequestInformation, AcProperty	requestObject 13
Schedule a report to run on particular days of the year.	AcExecuteObject, AcSchedule	requestObject 15
Schedule a report to run in one minute.	AcExecuteObject, AcSchedule	requestObject 16
Print a request on different printers using the Requster API.	See AcReqPrintReport in Actuate Client API Guide	requestObject 17
Stop a pending request.	AcStopPendingRequest	requestObject 18
Print an ROI using Report Server API with output going to a file.	AcPrintObject, AcProperty	requestObject 19
Print all active requests information for a user.	AcGetUserPendingRequests	requestObject 20
Print all the completed requests information for a user.	AcGetUserCompletedRequests	requestObject 21
Delete old completed requests for a user.	AcDeleteRequestStatusInformation, AcGetUserCompletedRequests	requestObject 22
Dump the names of users, their roles, and preferences.	AcGetUserNames, AcGetRolesOfUser	printerTable 1
Identify by name the available printers.	AcGetPrinterNames	printerTable 2
Get a description of a printer.	AcGetPrinterInformation	printerTable 3
Set printer defaults.	AcSetPrinterOptionDefaults, AcSetPrinterOptionDefaults, AcProperty	printerTable 4
Get printer defaults.	AcGetPrinterOptionDefaults, AcProperty	printerTable 5
Execute a request to print a report item.	AcPrintObject	printerTable 6
Set user printer preferences.	AcSetUserPrinterOptionDefaults	printerTable 7
Get user printer preferences.	AcGetUserPrinterOptionDefaults	printerTable 8
Execute and print a report on a repeat schedule.	AcExecuteAndPrintObject, AcSchedule	printerTable 9
Execute and print a report.	AcExecuteAndPrintObject, AcProperty	printerTable 10


Building egclient

Open the examples workspace called examples.mdp in the rsapi examples directory. In Visual C++, click Build→Rebuild All. If the build fails, see Setting up the development environment.


Running egclient

Run egclient either from a DOS window or the UNIX prompt using the following syntax:

Syntax

egclient -C<testClass> -T<testCaseNo> -1<[userArg1] -2[userArg2]
-3[userArg3]> -U<loginName> -P<password> -M<machine Name>
-H

-C

Specifies code in one of the functions, classified in one of the following test classes:

•	userTable

•	groupTable

•	channelTable

•	roleTable

•	reportObject

•	requestObject

•	printerTable

-T

Specifies the test number within the test class, as listed in Egclient functional overview.

-1, -2, and -3

Prefixes the first, second, and third parameter, if required.

-U

Your Actuate login name

-P

Your password

-M

The name of your machine

See also

Conquering tricky examples


Conquering tricky examples

This section covers potential pitfalls with several functions in egclient.

ReadObject

Incorrectly formatted arguments to the egclient ReadObject function are a common cause of failure. The following example shows how to enter a source file argument with the encyclopedia folder name Eastern Region. Because it is two words, the source file argument has to be enclosed in quotes. The ReadObject function reads from the forecast.rox report in the encyclopedia's Eastern Region folder and puts the bytes read in a file of the same name in the Temp directory of drive C.

C:\API Examples>egclientD -CreportObject -T7 -1"/Eastern Region/forecast.rox" -2C:\Temp\forecast.rox -Mhaleakala -UAdministrator

The output from executing this egclient function is:

Connected To Server With Status : 0

Object Name: /Eastern Region/forecast.rox

Bytes read: 384042


Writing a minimal application

To create the application, follow these steps:

1	Create message and new connection.

2	Set data members of message object, if required.

3	Send a request described by the message to the server.

See also

Pseudo-code
Actual code


Pseudo-code

The following pseudo-code describes the logic involved in connecting to the Report Server on machine M as user U, creating a request R, sending R to the server, and retrieving the server response.

// connect to server on machine M for user U, password P

AcClientConnection *C = new AcClientConnection("", M, U, P);

// if successful instantiate an AcRequest class

AcGetNumberOfUserLogins R;

// load R with data

R.SetUserName(U).

// send R to connected server, blocking other calls for a period of time

S = C->SendRequest( R, time);


Actual code

This example logs in to the Report Server as the user Administrator and sends a message asking how many Administrators are logged in to the Report Server. The answer is sent to standard output.

#include "acrsapi.h"

void   main(int argc, char* argv[])

{

#if defined (WIN32)

// Initialize RPC and WINSOCK libraries

AcRpcInit();

#endif

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcClientConnection  *m_connection;

AcClientConnection::AcConnectionStatus c_status;

RWCollectableString m_userName="Administrator", m_password="";

// Make connection to the server

m_connection = new AcClientConnection("","Haleakala",
m_userName,m_password);

c_status = m_connection->GetConnectionStatus();

if(c_status != AcClientConnection::AC_CONNECTION_OK) {

cerr << "Bad connection, aborting program. Status: " <<

AcClientConnectionStatusToString(c_status)  << endl;

cerr <<"Bad connection, aborting program. Status: " <<(int) c_status

<< endl;

exit(1);

  }

  else {

cout << "Connected To Server With  Status  : " << (int) c_status << endl;

  }

  AcGetNumberOfUserLogins noLoginUser;

  noLoginUser.SetUserName(m_userName);

  m_sendStatus=m_connection->SendRequest(noLoginUser, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed successfully" << endl;

unsigned long number = noLoginUser.GetNumberOfLogins();

cout << " Number of user logins : " << (int)number << endl;

}

}


Building and running the minimal application

The fastest way to build your minimal Report Server application is to use the workspace set up for egclient.

1	Delete egclient.cpp from the project files.

2	Add your minimal cpp file.

3	Rebuild all.

Open a DOS window and enter the name of the executable on the command line. The following is displayed:

C:\API Examples>egclient

Connected To Server With Status : 0
Function executed successfully
Number of user logins : 2
Connection Status  : 0
Operation Status  : 0


Report Server API reference

The Report Server API classes encapsulate functions that access the Report Server. Using the API, you can write applications that automate administrative and reporting tasks.

This section describes the Report Server API classes and member functions in alphabetical order.


AcAddChannel

Member functions of AcAddChannel

Creates a message for the administration server requesting creation of a channel with a specific name.

Description

This class is used in applications that access the Actuate Report Server via the World Wide Web and Actuate Web Agent service, which is added to Netscape or Microsoft Web Servers. Web Agent provides a clipping service of sorts called ReportCast Channels. ReportCast channels use push technology to push reports to particular web channels, where interested users can access and view them. With this class, your application can set up web-based channels. Subscribers to a particular channel view reports or other items available on that channel.

For examples, see egclient in the examples directory of the Report Server API. Check error messages for an empty channel object before adding a channel.

Public member function

Member function	Description
SetChannelName	Establishes the name of the channel to create.


Member functions of AcAddChannel

AcAddChannel::SetChannelName


AcAddChannel::SetChannelName

Sets the name of the channel to create.

Syntax

void SetChannelName(const RWCollectableString& name)

name

The name of the new channel.


AcAddGroup

Example   See also   Member functions of AcAddGroup

Represents a message for creating a new notification group.

Description

Creates a message for the administration server that requests creation of a new notification group with a specific name. A notification group is a tool for informing sets of users about completed requests and available reports. Initially, the group has no members. To add groups, client applications must connect to the Report Server with a user name that has the administrator role, such as the administrator user. That user automatically becomes the owner of the group.

Check error messages for an empty group object before adding a group.

Constructor

This class has default and copy constructors only.

Public member function

Member function	Description
SetGroupName	Sets the name of the new notification group.


Example

The following example shows how to add a group called Marketing to the administration server. This code assumes a server connection called m_connection already exists.

RWCollectableString name="Marketing";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcAddGroup addGroupMsg;

addGroupMsg.SetGroupName(name);

m_sendStatus =m_connection->SendRequest(addGroupMsg, m_timeout);


See also

AcClientConnection


Member functions of AcAddGroup

AcAddGroup::SetGroupName


AcAddGroup::SetGroupName

Sets the name of the new notification group.

Syntax

void SetGroupName(const RWCollectableString& name)

name

A text string representing the name of the new group.


AcAddPrivilege

Member functions of AcAddPrivilege

Represents a message for adding a privilege type.

Description

Creates a message for the administration server that requests addition of a privilege type to the system. A privilege is a security feature that defines the relationship between a user and an encyclopedia item or channel. Read, write, delete, execute, and grant privileges are built in, but client applications may add additional privileges to implement new security features.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetPrivilegeType	Specifies which privilege to add.


Member functions of AcAddPrivilege

AcAddPrivilege::SetPrivilegeType


AcAddPrivilege::SetPrivilegeType

Specifies which privilege to add.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the new privilege type. For more information, see privilege_type.


AcAddPrivilegeToRole

Example   See also   Member functions of AcAddPrivilegeToRole

Represents a message to set up privileges between a role and a report item.

Description

Creates a message for the administration server that establishes a privilege relationship between a role and a Report Encyclopedia item. Before instantiating this class, the client application must connect to the server using a user name with grant privilege on the encyclopedia item. Once the server authenticates the request, it adds the privilege to the report item's access list, so users with the specified role have the new access privilege.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetChannelName	Establishes the name of the channel for the privilege relationship.
SetObjectID	Uses the object's identification to specify the encyclopedia item for the privilege relationship.
SetObjectName	Uses the object's name to specify the encyclopedia item for the privilege relationship.
SetPrivilegeType	Specifies the type of privilege relationship between the role and the encyclopedia item.
SetRoleName	Sets the role name for the privilege relationship.


Example

The following example shows how to add read privilege to a role named Manager for an object called byfr.roi in the Eastern Region folder. This code assumes that a server connection called m_connection exists.

RWCollectableString roleName="Manager";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcAddPrivilegeToRole addPrivToRoleMsg;

addPrivToRoleMsg.SetRoleName(roleName);

addPrivToRoleMsg.SetObjectName("/Eastern Region/byfr.roi");

addPrivToRoleMsg.SetPrivilegeType(AC_PRIVILEGE_TYPE_READ);

m_sendStatus =m_connection->SendRequest(addPrivToRoleMsg,

m_timeout);


See also

AcClientConnection


Member functions of AcAddPrivilegeToRole

AcAddPrivilegeToRole::SetChannelName

AcAddPrivilegeToRole::SetObjectID

AcAddPrivilegeToRole::SetObjectName

AcAddPrivilegeToRole::SetPrivilegeType

AcAddPrivilegeToRole::SetRoleName


AcAddPrivilegeToRole::SetChannelName

Establishes the name of the channel on which to grant privileges.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

Description

Sets the name of the channel to have the privilege set on. Only an object or a channel, but not both, may be set in a specific privilege message.


AcAddPrivilegeToRole::SetObjectID

See also

Specifies the encyclopedia item, by ID, for the privilege relationship.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the object. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.

Description

This function uses the object's ID for identification. The alternate procedure, SetObjectName, uses the object's name.


See also

AcAddPrivilegeToRole::SetObjectName


AcAddPrivilegeToRole::SetObjectName

See also

Specifies the encyclopedia item, by name, for the privilege relationship.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object.

Description

This function uses the object's name for identification. The alternate procedure, SetObjectID, uses the object's ID. The function takes the full name of the object, including the hierarchical path, filename, and file extension of the object. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path.


See also

AcAddPrivilegeToRole::SetObjectID


AcAddPrivilegeToRole::SetPrivilegeType

Specifies a privilege that defines the relationship between the role and the encyclopedia item.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the privilege type. For more information, see privilege_type.


AcAddPrivilegeToRole::SetRoleName

Sets the role name for the privilege relationship.

Syntax

void SetRoleName(const RWCollectableString& role_name)

role_name

The name of the role, which must be valid on the administration server, to be granted the privilege.


AcAddPrivilegeToUser

Example   See also   Member functions of AcAddPrivilegeToUser

Represents a message to assign system privileges on a report item to a user.

Description

Creates a message for the administration server that establishes a privilege relationship between a user and an encyclopedia item. For example, the client application can assign the execute privilege for a report executable to a user.

Report encyclopedia security requires the client application to connect to the server as a user with grant privilege on the encyclopedia item, normally the owner or system administrator. Once the server authenticates the request, it adds the user privilege to the encyclopedia item's access list.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetChannelName	Establishes the name of the channel to have privileges granted.
SetObjectName	Uses the name of the object to specify the encyclopedia item for the privilege relationship.
SetObjectID	Uses the ID of the object to specify the encyclopedia item for the privilege relationship.
SetPrivilegeType	Sets a privilege that defines the relationship between the user and the encyclopedia item.
SetUserName	Sets the user name for the privilege relationship.


Example

The following example shows how to assign execute privileges for a report object called byfr.rox in the Eastern Region folder to a user named William. This code assumes a server connection called m_connection already exists.

RWCollectableString userName="William";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcAddPrivilegeToUser addPrivToUserMsg;

addPrivToUserMsg.SetUserName(userName);

addPrivToUserMsg.SetObjectName("/Eastern Region/byfr.rox");

addPrivToUserMsg.SetPrivilegeType(AC_PRIVILEGE_TYPE_EXECUTE);

m_sendStatus =m_connection->SendRequest(addPrivToUserMsg,

m_timeout);


See also

AcClientConnection


Member functions of AcAddPrivilegeToUser

AcAddPrivilegeToUser::SetChannelName

AcAddPrivilegeToUser::SetObjectName

AcAddPrivilegeToUser::SetObjectID

AcAddPrivilegeToUser::SetPrivilegeType

AcAddPrivilegeToUser::SetUserName


AcAddPrivilegeToUser::SetChannelName

Establishes the name of the channel to which the privilege applies.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

channel_name

The name of the channel to have the privilege set on.

Description

Sets the name of the channel to have the privilege set on. Only an object or a channel, but not both, may be set in a specific privilege message.


AcAddPrivilegeToUser::SetObjectName

See also

One of two ways to specify the encyclopedia item for the privilege relationship.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object.

Description

This function uses the object's name for identification. The alternate procedure, SetObjectID, uses the object's ID, if available. Set the object_name parameter to the full name of the object, including the hierarchical path, filename, and extension. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path. Actuate uses the forward slash to separate paths.


See also

AcAddPrivilegeToUser::SetObjectID


AcAddPrivilegeToUser::SetObjectID

See also

One of two ways to specify the encyclopedia item for the privilege relationship.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the object.

Description

This function uses the object's ID for identification. The alternate procedure, SetObjectName, uses the object's name. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.


See also

AcAddPrivilegeToUser::SetObjectName


AcAddPrivilegeToUser::SetPrivilegeType

Sets a privilege that defines the relationship between the user and the encyclopedia item.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the privilege type.

The following table lists the privileges that can be applied to items in the encyclopedia. Each row describes a single privilege and explains what the privilege means for different types of items.

Property	Privilege	Item type	Meaning
AC_PRIVILEGE_ TYPE_READ	Read	Report document	Client applications that connect with the server as a user with read privilege on the report document can view the document if that user also has read privilege on the associated report executable.
		All other types	Client applications that connect with the server as a user with read privilege on other types can examine the item's properties and view or print the item's contents. If the item is a folder, the client application can examine the contents.
AC_PRIVILEGE_ TYPE_WRITE	Write	Folder	Client applications that connect to the server as a user with write privilege on a folder can create new items in the folder, paste items into it, or rename it. Client applications can also move the folder to a different containing folder, assuming the account has read and write privileges on the destination folder.
		All other types	Client applications that connect to the server as a user with write privilege on other types can rename the item. Client applications can also move the item to a different containing folder, assuming the account has read and write privileges on the destination folder.
AC_PRIVILEGE_ TYPE_DELETE	Delete	Folder	Client applications that connect to the server as a user with delete privileges on a folder can delete the folder if the user's account also has delete privilege on all the items in the folder.
		All other types	Client applications that connect to the server as a user with delete privileges on other types can delete the item.
AC_PRIVILEGE_ TYPE_EXECUTE	Execute	Report executable, report parameter value	Client applications that connect to the server as a user with execute privileges on a report can schedule a new request for the item. In addition, the user's account must have read and write privileges to the folder where the generated report document will be stored, and to an existing report document if it will be versioned or replaced by the new report document.
AC_PRIVILEGE_ TYPE_GRANT	Grant	All types	Client applications that connect to the server as a user with grant privileges on an item can grant any privilege on the item, including the grant privilege, to other users.
AC_PRIVILEGE_ TYPE_READ_ PARAMETERS	Read Parameters	Parameters	Client applications that connect to the server as a user with read parameters privileges can view the parameters set for the item.
AC_PRIVILEGE_ TYPE_VISIBLE	Visible		Client applications that connect to the server as a user with visible privileges on an item can view contained objects of the object even if the user has no privileges on the container object itself.


AcAddPrivilegeToUser::SetUserName

Sets the user name for the privilege relationship.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcAddRole

Member functions of AcAddRole

Represents a message to create a new user-defined role.

Description

Creates a message for the administration server that requests creation of a new user-defined role. A role is an administration tool that groups users with similar privileges. Roles simplify the task of granting the same privileges to a group of users and help users and administrators manage privilege sets as the environment changes. Client applications should connect to the server with the user name of the desired role owner. The new role has no privileges initially.

The Report Server has two permanent roles:

•	Administrator

•	All

The Administrator role is unique because it exists when you first start the system and cannot be removed. The Administrator role has all privileges, which cannot be revoked, for all objects.

The All role, which includes every user, provides a convenient way to assign object privileges to everyone. For example, programmers can allow everyone to read a report by assigning the read privilege for the report to the All role.

Before adding a role, check error messages for an empty role object.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the user-defined name for the role.


Member functions of AcAddRole

AcAddRole::SetRoleName


AcAddRole::SetRoleName

Sets the user-defined name for the role.

Syntax

void SetRoleName(const RWCollectableString& name)

name

A user-defined text string that represents the name of the role. Typically, role names suggest their scope of responsibility or geographic region, such as manager or Eastern Region.


AcAddRoleToRole

Member functions of AcAddRoleToRole

Represents a message to create a hierarchy between two roles.

Description

Creates a message for the server that requests creation of a hierarchical role relationship between two roles. After the message is sent, the role receiving the role is the higher of the two in the hierarchy and inherits the privileges of the added role. The added role may itself have inherited privileges, which it passes to roles above it in the hierarchy. When there are multiple hierarchical paths between a role and an object, the role inherits the privileges of the object with the highest privileges. The inheritance hierarchy can have as many levels as desired. The client application must connect with the server as a user with grant privilege on the added role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the name of the role that inherits the additional role.
SetRoleNameToAdd	Sets the name of the role to add.


Member functions of AcAddRoleToRole

AcAddRoleToRole::SetRoleName

AcAddRoleToRole::SetRoleNameToAdd


AcAddRoleToRole::SetRoleName

Sets the name of the role that inherits the additional role.

Syntax

void SetRoleName(const RWCollectableString& role_name)

role_name

The name of the superior role, which must be a valid role on the administration server.

Description

When processed by the administration server, the named role will be higher in the hierarchy than the additional role.


AcAddRoleToRole::SetRoleNameToAdd

Sets the name of the role to add.

Syntax

void SetRoleNameToAdd(const RWCollectableString& role_name_to_add)

role_name_to_add

The name of the subordinate role, which must be a valid role on the administration server.

Description

When processed by the administration server, this role will be the lower of the two in the hierarchy.


AcAddRoleToUser

Example   Member functions of AcAddRoleToUser

Represents a message to add a user to a role.

Description

Creates a message for the administration server that requests addition of a user to an existing role. Use this class to associate groups of users who have common requirements for accessing the encyclopedia with a common role. Generally, client applications manage role membership by connecting to the server as the owner of the role. The privileges associated with the role and its members are established separately.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user to include in the role.
SetRoleName	Sets the name of the role the user joins.


Example

The following example shows how to add a user named William to a role called Manager. This code assumes that a server connection called m_connection already exists.

RWCollectableString name="William", roleName="Manager";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcAddRoleToUser addRoleToUserMsg;

addRoleToUserMsg.SetUserName(name);

addRoleToUserMsg.SetRoleName(roleName);

m_sendStatus =m_connection->SendRequest(addRoleToUserMsg,

m_timeout);


Member functions of AcAddRoleToUser

AcAddRoleToUser::SetUserName

AcAddRoleToUser::SetRoleName


AcAddRoleToUser::SetUserName

Sets name of the user to include in the role.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcAddRoleToUser::SetRoleName

Sets the name of the role the user joins.

Syntax

void SetRoleName(const RWCollectableString& role_name_to_add)

role_name_to_add

The name of the desired role, which must be a valid role name on the administration server.


AcAddUser

Example   Member functions of AcAddUser

Represents a message to create a new user.

Description

Creates a message for the administration server that requests creation of a new user with a specific name and password. To add users, client applications must connect to the Report Server with a user name that has the administrator role, such as the administrator user. The administrator user is unique because it is a permanent user that the system automatically creates during Report Server installation.

When the server adds a user it automatically assigns a unique user ID. The Report Server uses user IDs to associate users with objects, event notifications, and other internal tasks. For information on accessing user IDs, see AcGetIDFromName.

Constructor

This class has default and copy constructors only.


Example

The following example shows how to add a new user named William with no password. The code assumes a server connection called m_connection already exists.

RWCollectableString name="William", password="";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

// Check error messages for an empty user object

AcAddUser addUserMsg;

addUserMsg.SetUserName(name);

addUserMsg.SetPassword(password);

m_sendStatus =m_connection->SendRequest(addUserMsg, m_timeout);

Public member functions

Member function	Description
SetUserName	Sets the name of the new user.
SetPassword	Sets the password of the new user.


Member functions of AcAddUser

AcAddUser::SetUserName

AcAddUser::SetPassword


AcAddUser::SetUserName

Sets the name of the new user in this message object.

Syntax

void SetUserName(const RWCollectableString& name)

name

A text string representing the user's name. The string can contain upper and lower case characters, but subsequent authentications are not case-sensitive.


AcAddUser::SetPassword

Sets the password of the new user in this message object.

Syntax

void SetPassword(const RWCollectableString& password)

password

A case-sensitive text string representing the user's password.

Description

Password information for all clients and services are stored in encrypted password repositories on the server. Only the administration servers know how to read and write the password repositories.

When a client account or service is created, updated, or removed, it must be done through the administration server. All messages containing password information are encrypted using an encryption key known only by the administration server and the API implementation for accessing the administration server.


AcAddUserToGroup

Example   See also   Member functions of AcAddUserToGroup

Represents a message to add a user to a group.

Description

Creates a message for the administration server that requests addition of a user to a group. Client applications use this class to build a group of users that have common requirements for event notification. Since this is an administrative task, client applications must connect to the Report Server as a user with the administrator role. Also, the user and group must exist in the administration server before invoking this procedure.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user to add to the group.
SetGroupName	Sets the name of the group.


Example

The following example shows how to add a user named William to a group named Marketing. This code assumes a server connection called m_connection already exists.

RWCollectableString groupName="Marketing", userName="William";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcAddUserToGroup addUserToGroupMsg;

addUserToGroupMsg.SetGroupName(groupName);

addUserToGroupMsg.SetUserName(userName);

m_sendStatus =m_connection->SendRequest(addUserToGroupMsg,
m_timeout);

Multiple users can be added to the same group by repeating the SetUserName and SendRequest functions for each user.


See also

AcClientConnection


Member functions of AcAddUserToGroup

AcAddUserToGroup::SetUserName

AcAddUserToGroup::SetGroupName


AcAddUserToGroup::SetUserName

Sets the name of the user to add to the group.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcAddUserToGroup::SetGroupName

Sets the name of the group for the specified user.

Syntax

void SetGroupName(const RWCollectableString& group_name)

group_name

A valid group name in the administration server.


AcChangeGroupName

Member functions of AcChangeGroupName

Represents a message to change the name of a group.

Description

Creates a message that instructs the server to change the name of a specific group. The renamed group retains its users and receives the same notifications as it did before the name change. To use this class, client applications must connect to the Report Server as a user with the administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetGroupName	Sets the old name of the group.
SetNewGroupName	Sets the new name for the group.


Member functions of AcChangeGroupName

AcChangeGroupName::SetGroupName

AcChangeGroupName::SetNewGroupName


AcChangeGroupName::SetGroupName

Sets the old name of the group in this message object.

Syntax

void SetGroupName(const RWCollectableString& name)

name

A valid group name in the administration server.


AcChangeGroupName::SetNewGroupName

Sets the new name for the group in this message object.

Syntax

void SetNewGroupName(const RWCollectableString& new_group_name)

new_group_name

A text string representing the new group name.


AcChangePassword

Member functions of AcChangePassword

This class represents a message to change a user's password.

Description

Creates a message for the administration server that requests a password change for the specified user. The client application must connect with the Report Server using the name and old password of the specified user or the name and password of a user with the administrator role.

After authentication of the request, the administration server encrypts the new password using a key that is only known by the administration server and the API.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user for the password change.
SetNewPassword	Sets the new password.


Member functions of AcChangePassword

AcChangePassword::SetUserName

AcChangePassword::SetNewPassword


AcChangePassword::SetUserName

Sets the name of the user for the password change.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcChangePassword::SetNewPassword

See also

Sets the new password string in this message object.

Syntax

void SetNewPassword(const RWCollectableString& new_password)

new_password

A new password.


See also

AcAddUser::SetPassword


AcChangeRoleName

Member functions of AcChangeRoleName

This class represents a message to change a role name.

Description

Creates a message for the administration server that requests a change to the name of a specific role. The client application must connect to the server as a user with grant privilege on the role or as a user with the administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the old role name in the message object.
SetNewRoleName	Sets the new role name in the message object.


Member functions of AcChangeRoleName

AcChangeRoleName::SetRoleName

AcChangeRoleName::SetNewRoleName


AcChangeRoleName::SetRoleName

Sets the old role name in the message object.

Syntax

void SetRoleName(const RWCollectableString& name)

name

The old name of the role and a valid role on the administration server.


AcChangeRoleName::SetNewRoleName

Sets the new role name in the message object.

Syntax

void SetNewRoleName(const RWCollectableString& new_role_name)

new_role_name

The new name for the role.


AcChangeUserName

Member functions of AcChangeUserName

This class represents a message to change a user's name.

Description

Creates a message for the administration server that changes the name of the specified user. The client application must connect with the Report Server as a user with the administration role and the server must recognize the old user name.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the old user name.
SetNewUserName	Sets the new user name.


Member functions of AcChangeUserName

AcChangeUserName::SetUserName

AcChangeUserName::SetNewUserName


AcChangeUserName::SetUserName

Sets the old user name in the message object.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcChangeUserName::SetNewUserName

Sets the new user name in this object.

Syntax

void SetNewUserName(const RWCollectableString& new_user_name)

new_user_name

A text string that represents the new user's name. The string can contain upper and lower case characters but subsequent authentications are not case sensitive.


AcChannelRequest

Member functions of AcChannelRequest

Represents a request that is sent to the Actuate Report Server via the World Wide Web and Actuate Web Agent service.

Constructor

This class has default and copy constructors.

Description

This class is a base class for deriving channel objects in applications that access the Actuate Report Server via the World Wide Web and Actuate Web Agent service. The Web Agent provides a clipping service of sorts called ReportCast channels. ReportCast channels use push technology to push reports to particular web channels, where interested users can access and view them.

Public member functions

Member function	Description
SetChannelName	Establishes the name of the channel for this request.


Member functions of AcChannelRequest

AcChannelRequest::SetChannelName


AcChannelRequest::SetChannelName

Sets the name of the channel for this request.

Syntax

void SetChannelName(const RWCollectableString& name)

name

The name of the new channel.


AcClientConnection

Example   Member functions of AcClientConnection

AcClientConnection objects represent a client connection to the Report Server system.

Description

The AcClientConnection class is used to connect to the Report Server and AcClientConnection objects must be provided in every client access to the server subsequent to the first connection. In addition to providing information about an actual connection, AcClientConnection objects contain authentication information used to authenticate every client request. AcClientConnection objects are reference counted.

Syntax

AcClientConnection(reserved, host_name_or_ip_address, user_name, password)

Constructor

AcClientConnection(reserved,
const RWCollectableString& host_name_or_ip_address,
const RWCollectableString& user_name,
const RWCollectableString& password)

reserved

Reserved for future implementations.

host_name_or_ip_address

The name of the physical machine or IP address for the connection.

user_name

The name of the client user connecting to the report system server.

password

The password of the user connecting to the Report Server system.

Public member functions

Function	Description
AcknowledgeNotice	Sends an acknowledgment to the original sender that the notice was received.
GetConnectionStatus	Returns the current status of this connection.
GetDefaultNameSpace	Returns the default name space associated with the specified machine.
GetHostName	Returns the host name for this connection.
GetHostNames	Returns a list of all the machines associated with the specified name space.
GetIPAddress	Returns the IP address for this connection.
GetIPAddresses	Returns a list of all IP addresses associated with the specified name space.
GetMessageSendError	Returns detail error information about a specific message transaction.
GetNameSpace	Returns the name space for this connection.
GetNameSpaces	Returns a list of all the name spaces associated with the specified machine.
GetSenderID	Returns the sender ID for this connection.
GetServerBuildNumber	Returns the build number of the Request Server when logging in.
ReceiveNotice	Receives a pending notice.
SendRequest	Sends a request message via the client connection.


Example

The following example shows how to establish a connection to the server. This code connects as an Administrator with no password.

AcClientConnection  *m_connection;

AcClientConnection::AcConnectionStatus status;

AcClientConnection::AcMessageSendStatus m_sendStatus;

RWCollectableString m_userName="Administrator", m_password="";

m_connection = new AcClientConnection("","paradise",

  m_userName,m_password);

  status = m_connection->GetConnectionStatus();

  if(status == AcClientConnection::AC_CONNECTION_OK) {

  // Message code goes here

  }

  else {

// Error code goes here

  }


Member functions of AcClientConnection

AcClientConnection::AcknowledgeNotice

AcClientConnection::GetConnectionStatus

AcClientConnection::GetIPAddress

AcClientConnection::GetMessageSendError

AcClientConnection::GetSenderID

AcClientConnection::GetServerBuildNumber

AcClientConnection::GetWorkingDirectory

AcClientConnection::ReceiveNotice

AcClientConnection::SetWorkingDirectory

AcClientConnection::SendRequest


AcClientConnection::AcknowledgeNotice

Sends an acknowledgment that the notice was received to the original sender of the notice.

Syntax

AcMessageSendStatus AcknowledgeNotice(const AcNotice& notice)

notice

The notice that was sent.

Description

This member function sends an acknowledgment that the notice was received to the originator of the notice.

Return value

The return value, a value of type AcMessageSendStatus, indicates the status of the attempt to send the message. After the transaction, the status value indicates success or failure of the attempt to send the message. The return values are defined by an enumerated data type with the following constants:

•	AC_SEND_OK

•	AC_SEND_WARNING

•	AC_SEND_WARNING_LAST

•	AC_SEND_ERROR

If the status is not AcConnection::AC_SEND_OK, there is additional warning or error information. Call the member function GetMessageSendInformation to get the additional information.


AcClientConnection::GetConnectionStatus

Returns the current status of this connection.

Syntax

AcClientConnectionStatus GetConnectionStatus() const

Description

Use this function to determine if the client connection is valid.

Return value

AcClientConnectionStatus values indicate the status of an AcClientConnection object's connection to the Report Server system. The return values are defined by a nested enumerated type as follows:

•	AC_CONNECTION_OK

•	AC_CONNECTION_WARNING_LAST

•	AC_CONNECTION_ERROR_TIMED_OUT

•	AC_CONNECTION_ERROR_ILLEGAL_USER_NAME

•	AC_CONNECTION_ERROR_ILLEGAL_NAME_SPACE

•	AC_CONNECTION_ERROR_ILLEGAL_HOST_NAME

•	AC_CONNECTION_ERROR_ILLEGAL_IP_ADDRESS

•	AC_CONNECTION_ERROR_ILLEGAL_PASSWORD

•	AC_CONNECTION_ERROR_PERMISSION_DENIED

•	AC_CONNECTION_ERROR_ILLEGAL_SERVER

•	AC_CONNECTION_ERROR_PORT_MAP_FAILURE

•	AC_CONNECTION_ERROR_CONNECTION_LOST

•	AC_CONNECTION_ERROR_CALLBACK_SETUP

•	AC_CONNECTION_ERROR_UNKNOWN_ERROR


AcClientConnection::GetIPAddress

Returns the IP address of the machine for this connection.

Syntax

RWCollectableString GetIPAddress() const

Description

This member function returns the IP address of the machine the client is connected to.

Return value

The IP address for this connection.


AcClientConnection::GetMessageSendError

Returns detailed error information about a specific sending of the specified message.

Syntax

AcMessageSendError GetMessageSendError(const AcMessage& message)

message

The message that was sent.

Description

This member function returns detailed error information about sending a message. The information about a specific send operation remains in memory until you retrieve it by calling this function or until the AcClientConnection object is destroyed.

Return value

Status of the message transaction. Any send that had a send status not equal to AcConnection::AC_SEND_OK will have send information waiting to be obtained.


AcClientConnection::GetSenderID

Returns the sender ID for this connection.

Syntax

AcSenderID GetSenderID() const

Description

This member function returns this connection's sender ID. The connection sets a sender ID on every message it sends. This ID is used as the login ID by the server.

Return value

The sender ID for this connection.


AcClientConnection::GetServerBuildNumber

Returns the build number defined by Actuate if login is successful.

Syntax

unsigned long AcClientConnection::GetServerBuildNumber() const

Description

If the Request Server executable is a debug or development executable, 0 is returned.


AcClientConnection::GetWorkingDirectory

Returns the working directory for persistent objects that use this connection.

Syntax

RWCollectableString GetWorkingDirectory() const

Description

This function accesses the name of the working directory of the persistent object. The name of the current working directory is prepended to the object name. The working directory returned by this function applies to persistent objects that use this connection only. Different connections may have different working directories.


AcClientConnection::ReceiveNotice

Receives a pending notice.

Syntax

AcNotice ReceiveNotice(unsigned int time_out_in_seconds)

timeout_in_seconds

The maximum amount of time the call blocks waiting for a reply to the receive notice call.

Description

This member function receives a pending notice. The function can be called in the CWinApp::OnIdle function to check for events during application idle time.

Return value

The returned AcNotice object may be the notification of the completion or failure of a request send or may be an event notice sent to this process. If there are no pending messages to receive, ReceiveNotice returns a NULL message; IsNull returns TRUE.


AcClientConnection::SetWorkingDirectory

Sets the current working directory for any persistent object that uses this connection.

Syntax

void SetWorkingDirectory(const RWCollectableString& directory_name)

directory_name

The fully-qualified path of the directory that will serve as the working directory for this connection.

Description

Sets the name of the working directory. Persistent objects that use this connection have directory_name prepended to their object name unless the object name does not start with a forward slash /, backward slash \, or tilde ~. The working directory applies to persistent objects that use this connection only. Different connections may have different working directories.


AcClientConnection::SendRequest

Sends a request message via the client connection.

Syntax

AcMessageSendStatus SendRequest(AcRequest&   request, unsigned int timeout_in_seconds)

request

The request that is sent.

timeout_in_seconds

The maximum amount of time the call blocks waiting for a reply to a request send.

Description

The member function SendRequest sends a request message via the client connection. The call blocks until a reply is returned. The state of the message object after the call returns depends on the type of message and its success or failure.

Return value

The return value, a value of type AcMessageSendStatus, indicates the status of the attempt to send the message. When a transaction is complete, the status value will indicate its success or failure. The return values are defined by a nested enum, as follows:

•	AC_SEND_OK

•	AC_SEND_WARNING

•	AC_SEND_WARNING_LAST

•	AC_SEND_ERROR

If the status is not AcConnection::AC_SEND_OK, additional warning or error information is available. Obtain the additional information by calling AcClientConnection::GetMessageSendError.


AcDeleteAllCompletedRequests

Member functions of AcDeleteAllCompletedRequests

Represents a message to delete requests in the Completed folder.

Description

Creates a message to delete all requests in a user's Request Completed folder in the Report Encyclopedia. When you run scheduled reports, information builds up in the Completed folder. This class represents a message to clear requests from the folder.

Constructor

This class has default and copy constructors only.

Public member function

Member function	Description
SetUserName	Specifies the user name to receive notification about the completed requests.


Member functions of AcDeleteAllCompletedRequests

AcDeleteAllCompletedRequests::SetUserName


AcDeleteAllCompletedRequests::SetUserName

Specifies the name of the user who is notified about the completed requests to be deleted.

Syntax

void SetUserName(const RWCollectable& user_name)

user_name

The name of user who is notified of completed requests. The default name is the name of the logged-in user.


AcDeleteChannel

See also   Member functions of AcDeleteChannel

Creates a message for the administration server that requests deletion of a specific channel.

Description

This class is used to remove a specified ReportCast channel that accessed the Actuate Report Server via the World Wide Web and Actuate Web Agent service. For more information, see egclient in the examples directory of the Report Server API.

Public member function

Member function	Description
SetChannelName	Specifies the name of the channel to be deleted.


See also

AcAddChannel::SetChannelName


Member functions of AcDeleteChannel

AcDeleteChannel::SetChannelName


AcDeleteChannel::SetChannelName

Sets the name of the channel to be deleted.

Syntax

void SetChannelName(const RWCollectableString& name)

name

The name of the channel.


AcDeleteGroup

Example   See also   Member functions of AcDeleteGroup

Represents a message to delete a group.

Description

Creates a message that instructs the administration server to delete a specific group. Deleting a group implicitly stops delivery of the event notifications to members of this group. To use this class, client applications must connect to the Report Server as a user with the administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetGroupName	Sets the name of the group to delete.


Example

The following example deletes a group called Marketing. This code assumes that a server connection called m_connection exists.

RWCollectableString groupName="Marketing";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcDeleteGroup deleteGroupMsg;

deleteGroupMsg.SetGroupName(groupName);

m_sendStatus =m_connection->SendRequest(deleteGroupMsg, m_timeout);


See also

AcClientConnection


Member functions of AcDeleteGroup

AcDeleteGroup::SetGroupName


AcDeleteGroup::SetGroupName

Sets the name of the group to delete.

Syntax

void SetGroupName(const RWCollectableString& name)

name

A valid group name on the administration server.


AcDeletePrivilege

Member functions of AcDeletePrivilege

Represents a message to delete a privilege type.

Description

Creates a message for the administration server that requests deletion of a privilege type. Any remaining references to the privilege have no effect. Only user-defined privileges can be deleted from the system.

Constructor

This class has default and copy constructors only.

Public member function

Member function	Description
SetPrivilegeType	Sets the type of privilege to delete.


Member functions of AcDeletePrivilege

AcDeletePrivilege::SetPrivilegeType


AcDeletePrivilege::SetPrivilegeType

Sets the type of privilege to delete.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the privilege type. For more information, see privilege_type.


AcDeletePrivilegeFromRole

See also   Member functions of AcDeletePrivilegeFromRole

Represents a message to remove privileges from a role.

Description

Creates a message for the administration server that removes the privilege relationship between a role and an encyclopedia item. To delete a privilege, the client application must connect with the server as a user with grant privilege on the encyclopedia item. Once the server authenticates the request, it removes the privilege from the access list of the encyclopedia item so that role members no longer have the access privilege.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetChannelName	Specifies by name the channel with the privilege relationship to be deleted.
SetObjectName	Uses the object's name to specify the encyclopedia item with the privilege relationship to be deleted.
SetObjectID	Uses the object's identification to specify the encyclopedia item with the privilege relationship to be deleted.
SetPrivilegeType	Sets a privilege type to delete from the encyclopedia item's access list.
SetRoleName	Sets the role name with an existing privilege relationship to be deleted.


See also

AcAddPrivilegeToRole


Member functions of AcDeletePrivilegeFromRole

AcDeletePrivilegeFromRole::SetChannelName

AcDeletePrivilegeFromRole::SetObjectName

AcDeletePrivilegeFromRole::SetObjectID

AcDeletePrivilegeFromRole::SetPrivilegeType

AcDeletePrivilegeFromRole::SetRoleName


AcDeletePrivilegeFromRole::SetChannelName

Establishes the name of the channel from which to remove privileges.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

Description

Sets the name of the channel from which to remove privileges. Set either a channel name or an object name, but not both, in the message to remove privileges.


AcDeletePrivilegeFromRole::SetObjectName

See also

Specifies the encyclopedia item with the privilege relationship, by name.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object. This is the full name of the object, including the hierarchical path, filename, and file extension of the object. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path.

Description

This function uses the object's name to identify the item from which to remove privileges.


See also

AcDeletePrivilegeFromRole::SetObjectID


AcDeletePrivilegeFromRole::SetObjectID

See also

Specifies the encyclopedia item with the privilege relationship, by object ID.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the object. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.

Description

This function uses the object's ID for identification. The alternate procedure, SetObjectName, uses the object's name.


See also

AcDeletePrivilegeFromRole::SetObjectName


AcDeletePrivilegeFromRole::SetPrivilegeType

See also

Sets a privilege to delete from the encyclopedia item access list.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the privilege type. For more information, see privilege_type.


See also

AcAddPrivilegeToUser::SetPrivilegeType


AcDeletePrivilegeFromRole::SetRoleName

Sets the role name with a privilege relationship to be deleted.

Syntax

void SetRoleName(const RWCollectableString& role_name)

role_name

The name of the role whose privileges are deleted. The role must be a valid role on the administration server.


AcDeletePrivilegeFromUser

See also   Member functions of AcDeletePrivilegeFromUser

Represents a message to remove a user's privilege.

Description

Creates a message for the administration server that removes the privilege relationship between a user and an encyclopedia item. Report encyclopedia security requires the client application to connect to the server as a user, such as the owner or system administrator, with grant privilege on the encyclopedia item. Once the server authenticates the request, it removes the user privilege from the access list of the encyclopedia item.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetChannelName	Establishes the name of the channel from which to remove the user privilege relationship.
SetObjectID	Uses the object identification to specify the encyclopedia item with the privilege relationship.
SetObjectName	Uses the object name to specify the encyclopedia item with the privilege relationship.
SetPrivilegeType	Sets a privilege type to delete from the encyclopedia item access list.
SetUserName	Sets the name of the user who has an existing privilege relationship with an encyclopedia item.


See also

AcAddPrivilegeToUser


Member functions of AcDeletePrivilegeFromUser

AcDeletePrivilegeFromUser::SetChannelName

AcDeletePrivilegeFromUser::SetObjectID

AcDeletePrivilegeFromUser::SetObjectName

AcDeletePrivilegeFromUser::SetPrivilegeType

AcDeletePrivilegeFromUser::SetUserName


AcDeletePrivilegeFromUser::SetChannelName

Establishes the name of the channel with the privilege relationship to be deleted. Only an object or a channel, but not both, may be set in a specific privilege message.

Syntax

void SetChannelName(const RWCollectableString& channel_name)


AcDeletePrivilegeFromUser::SetObjectID

See also

Specifies the encyclopedia item, by object ID, with the privilege relationship to be deleted.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the object. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.

Description

This function uses the object ID to identify the object to delete privileges from for the specified user.


See also

AcDeletePrivilegeFromUser::SetObjectName


AcDeletePrivilegeFromUser::SetObjectName

See also

Specifies the encyclopedia item, by name, with the privilege relationship to be deleted.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object. This is the full name of the object, including the hierarchical path, filename, and extension of the object. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path.

Description

This function uses the object name to identify the object to delete privileges from for the specified user.


See also

AcDeletePrivilegeFromUser::SetObjectID


AcDeletePrivilegeFromUser::SetPrivilegeType

See also

Specifies which privilege to delete from the encyclopedia item's access list.

Syntax

void SetPrivilegeType(const RWCollectableString& privilege_type)

privilege_type

A text string corresponding to the privilege type. For more information, see privilege_type.


See also

AcAddPrivilegeToUser::SetPrivilegeType


AcDeletePrivilegeFromUser::SetUserName

Sets the name of the user who has an existing privilege relationship with an encyclopedia item.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The name of the user who is in the access list of the encyclopedia item and whose privilege is deleted.


AcDeleteRequest

Member functions of AcDeleteRequest

Creates a message to delete the specified request.

Constructor

This class has default and copy constructors.

Public member function

Member function	Description
SetRequestID	Specifies the ID of the request to delete.


Member functions of AcDeleteRequest

AcDeleteRequest::SetRequestID


AcDeleteRequest::SetRequestID

Example

Specifies the ID of the request to delete.

Syntax

void SetRequestID(const RWCollectableString& request_id)

request_id

The identifier for the request.


Example

This example deletes a scheduled request by request ID.

RWCollectableString requestId = "050397 21:09:33 36";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcDeleteRequest delReq;

delReq.SetRequestID(requestId);

m_sendStatus =m_connection->SendRequest(delReq, m_timeout);


AcDeleteRequestInstanceStatusInformation

Member functions of AcDeleteRequestInstanceStatusInformation

Creates a message to delete the status information for a particular instance of a request, usually a scheduled one.

Description

Creates a message to destroy a particular occurrence of status information. Repeat scheduling of an operation request often builds up status information (a list of properties) which this class deletes by instance. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Constructors

This class has default and copy constructors.

Public member functions

Member function	Description
SetChannelName	Establishes the name of the channel for accessing requests with status information to be deleted.
SetRequestID	Establishes the ID of the request to be deleted.
SetRequestInstanceStartDate AndTime	Specifies the execution date and time of the request instance with the status information to be deleted.
SetRequestInstanceStartDate AndTimes	Specifies a list of scheduled execution dates and times of a request instance with status information to be deleted.
SetUserName	Specifies the user to notify with the status information.


Member functions of AcDeleteRequestInstanceStatusInformation

AcDeleteRequestInstanceStatusInformation:: SetChannelName

AcDeleteRequestInstanceStatusInformation:: SetRequestID

AcDeleteRequestInstanceStatusInformation:: SetRequestInstanceStartDateAndTime

AcDeleteRequestInstanceStatusInformation:: SetRequestInstanceStartDateAndTimes

AcDeleteRequestInstanceStatusInformation:: SetUserName


AcDeleteRequestInstanceStatusInformation:: SetChannelName

Specifies the ReportCast channel name for accessing requests with status information to be deleted.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

channel_name

A text string representing the channel name.


AcDeleteRequestInstanceStatusInformation:: SetRequestID

Specifies the ID of the request to be deleted. Inherited from AcRequestRequest.

Syntax

void SetRequestID(const RWCollectableString& requestID);

request_id

The request ID.


AcDeleteRequestInstanceStatusInformation:: SetRequestInstanceStartDateAndTime

Specifies a list of scheduled execution dates and times of a request instance with status information to be deleted. A request with status information on or before the given date and time is deleted. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetRequestInstanceStartDateAndTime(const RWCollectableTime& date_and_time)

date_and_time

The request instance date and time.


AcDeleteRequestInstanceStatusInformation:: SetRequestInstanceStartDateAndTimes

Specifies the date and time of a list of request instances with status information to be deleted.

Syntax

void SetRequestInstanceStartDateAndTimes(const RWOrdered& date_and_time_list)

date_and_time_list

The request instance date and time list of type RWOrdered, which is an ordered polymorphic collection of objects. Call RWOrdered::CloseAndDestroy to delete the collection. The date and time are in UTC format, for example
04/23/97 13:18:15.

Description

This function specifies information to be deleted for requests on a repeat schedule that creates multiple instances at scheduled times. Status information about requests executed on or before the given list of dates and times are deleted. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.


AcDeleteRequestInstanceStatusInformation:: SetUserName

Specifies the user to notify with the status information. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The user name.


AcDeleteRequestStatusInformation

Example   Member functions of AcDeleteRequestStatusInformation

Creates a message to delete the status information about the specified request.

Description

Creates a message to destroy unwanted status information objects that result from a scheduled request being executed multiple times. Repeat scheduling of an operation request builds up status information, which this function deletes for a report run at a particular time or under certain conditions. Status information is a list of properties. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetChannelName	Specifies the channel name that has requests with status information to be deleted.
SetDateAndTime	Specifies the deletion of status information dated on or earlier than a particular date and time.
SetRequestId	Specifies the ID of the request.
SetUserName	Names the user who receives status information about the request to be deleted.


Example

This example shows how to delete status information sent to William regarding notification of executions of request 050397 21:57:48 37. Status information on requests dated earlier than now (the current server time) are deleted.

RWCollectableString userName = "William";

RWCollectableString requestId = "050397 21:57:48 37";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcGetServerTime serverTimeInfo;

m_sendStatus =m_connection->SendRequest(serverTimeInfo,

  m_timeout);

RWCollectableTime serverTime;

serverTime= serverTimeInfo.GetServerTime();

AcDeleteRequestStatusInformation reqInfo;

reqInfo.SetDateAndTime(serverTime);

reqInfo.SetRequestID(requestId);

reqInfo.SetUserName(userName);

m_sendStatus =m_connection->SendRequest(reqInfo, m_timeout);


Member functions of AcDeleteRequestStatusInformation

AcDeleteRequestStatusInformation:: SetChannelName

AcDeleteRequestStatusInformation:: SetDateAndTime

AcDeleteRequestStatusInformation:: SetRequestID

AcDeleteRequestStatusInformation::SetUserName


AcDeleteRequestStatusInformation:: SetChannelName

Specifies the channel name that has requests with status information to be deleted.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

channel_name

The text string representing the channel name.


AcDeleteRequestStatusInformation:: SetDateAndTime

Specifies the deletion of status information dated on or earlier than a particular date and time. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetDateAndTime(const RWCollectableTime& date_and_time)

date_and_time

The day, month, year and time formatted in UTC (Universal Time Code). For example, 04/23/97 13:18:15.


AcDeleteRequestStatusInformation:: SetRequestID

Specifies the ID of the request. Inherited from AcRequest.

Syntax

void SetRequestID(const RWCollectableString& request_id)

request_id

The identifier for the request.


AcDeleteRequestStatusInformation::SetUserName

Names the user who receives status information about the request to be deleted. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetUserName(const RWCollectableString& userName)

user_name

The string representing the name of the user.


AcDeleteRole

Member functions of AcDeleteRole

Represents a message to delete a role.

Description

Creates a message for the administration server that requests deletion of a role. To use this class, client applications must connect to the server as the role owner or as a user with the administrator role. Once deleted, all privileges associated with the role are revoked.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the name of the role to delete.


Member functions of AcDeleteRole

AcDeleteRole::SetRoleName


AcDeleteRole::SetRoleName

Sets the name of the role to delete.

Syntax

void SetRoleName(const RWCollectableString& name)

name

The name of the role, which must be a valid role on the administration server.


AcDeleteRoleFromRole

Member functions of AcDeleteRoleFromRole

Represents a message to delete a hierarchy between roles.

Description

Creates a message for the server that requests deletion of a hierarchical role relationship between two roles. Once the relationship is deleted, the receiving role no longer inherits the privileges of the giving role. The client application must connect with the server as a user with grant privilege on the superior role to execute this function.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the name of the privilege-receiving role that will shed the relationship with the giving role.
SetRoleNameToDelete	Sets the name of the privilege-giving role.


Member functions of AcDeleteRoleFromRole

AcDeleteRoleFromRole::SetRoleName

AcDeleteRoleFromRole::SetRoleNameToDelete


AcDeleteRoleFromRole::SetRoleName

Sets the name of the role that will shed a role.

Syntax

void SetRoleName(const RWCollectableString& role_name)

role_name

The name of the role that receives the privileges, which must be a valid role on the administration server.


AcDeleteRoleFromRole::SetRoleNameToDelete

Sets the name of the role that gives the privileges that will be removed when the relationship is deleted.

Syntax

void SetRoleNameToDelete(const RWCollectableString& role_name_to_delete)

role_name_to_delete

The name of the privilege-giving role, which must be a valid role on the administration server.


AcDeleteRoleFromUser

See also   Member functions of AcDeleteRoleFromUser

Represents a message to delete a user from a role.

Description

Creates a message for the administration server that requests deletion of a user from an existing role. Generally, client applications manage role membership by connecting to the server as the owner of the role. Once authenticated, all privileges granted to this user by this role are revoked.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user to delete from the role.
SetRoleName	Sets the name of the role to delete the user from.


See also

AcAddRoleToUser


Member functions of AcDeleteRoleFromUser

AcDeleteRoleFromUser::SetUserName

AcDeleteRoleFromUser::SetRoleName


AcDeleteRoleFromUser::SetUserName

Sets the name of the user to delete from the role.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The name of a user currently associated with the role.


AcDeleteRoleFromUser::SetRoleName

Sets the name of the role from which to delete the user.

Syntax

void SetRoleName(const RWCollectableString& role_name_to_add)

role_name_to_add

The role associated with the user. It must be a valid role name on the administration server.


AcDeleteUser

Example   Member functions of AcDeleteUser

Represents a message to delete a user.

Description

Creates a message for the administration server that requests deletion of a specific user. The client application must connect with the Report Server as a user with the administrator role. The administrator user cannot be deleted.

To maintain database integrity, an object owned by a deleted user is automatically owned by the administrator user.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user to delete


Example

The following example shows how to delete a user named William, who has no password. This code assumes a server connection called m_connection already exists.

RWCollectableString name="William", password="";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcDeleteUser deleteUserMsg;

deleteUserMsg.SetUserName(name);

m_sendStatus =m_connection->SendRequest(deleteUserMsg, m_timeout);


Member functions of AcDeleteUser

AcDeleteUser::SetUserName


AcDeleteUser::SetUserName

Sets the name of the user to delete.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcDeleteUserFromGroup

Member functions of AcDeleteUserFromGroup

Represents a message to delete a user from a group.

Description

Creates a message that instructs the administration server to delete a specific user from a specific group. Once deleted, the user no longer receives event notifications associated with the group. To use this class, client applications must connect to the Report Server as a user with the administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user to delete.
SetGroupName	Sets the name of the group that includes the user.


Member functions of AcDeleteUserFromGroup

AcDeleteUserFromGroup::SetUserName

AcDeleteUserFromGroup::SetGroupName


AcDeleteUserFromGroup::SetUserName

Sets the name of the user to delete.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcDeleteUserFromGroup::SetGroupName

Sets the name of the group that includes the user.

Syntax

void SetGroupName(const RWCollectableString& group_name)

group_name

A valid group name on the administration server.


AcExecuteAndPrintObject

Example   Member functions of AcExecuteAndPrintObject

Creates a message that requests executing and printing the accompanying report item.

Description

This function is used to execute and print a report item. Use the request ID returned by the message to get the status and results of the request to execute and print the object.

Constructor

This class has default and copy constructors.

Public member functions

These member functions are the same as AcExecuteObject's, except the SetRequestOptions function of AcExecuteAndPrintObject includes options to request printing in addition to executing.

Member function	Description
GetRequestID	Returns the ID of the request.
SetBundledFlag	Use this function to bundle two objects, such as an ROI and ROX.
SetInputObjectID	Specifies by ID the target object for executing the request.
SetInputObjectName	Specifies by name and version the target object, ROX or Basic file, for executing the request.
SetOutputObjectName	Specifies the output object name for this request.
SetOutputObjectVersionName	Specifies the version name to be set on the output object created by this request.
SetPrinterName	Sets the name of the printer.
SetPriority	Specifies the scheduling precedence for running the reports associated with this request.
SetRequestOptions	Sets options, AcProperty objects, to be used with this request.
SetSchedule	Sets the repeat schedule of the request.
SetValuesObjectID	Specifies by ID the values object for getting database usernames, passwords, and other execution options.
SetValuesObjectName	Specifies by name the values object for getting database usernames, passwords, and other execution options.


Example

This example assumes that a connection, represented by the m_connection pointer, has been made. A message is set up and sent to execute an ROX named forecast and to print the ROI on a LaserJet IIP on the machine lahaina.

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcExecuteAndPrintObject eAndp;

eAndp.SetInputObjectName("/Eastern Region/forecast.rox");

eAndp.SetValuesObjectName("/Eastern Region/forecast.rov");

eAndp.SetOutputObjectName("/Eastern Region/forecast.roi",TRUE);

eAndp.SetPrinterName("\\\\lahaina\\HP LASERJET IIP");

m_sendStatus =m_connection->SendRequest(  eAndp, m_timeout);


Member functions of AcExecuteAndPrintObject

AcExecuteAndPrintObject::GetRequestID

AcExecuteAndPrintObject::SetBundledFlag

AcExecuteAndPrintObject::SetInputObjectID

AcExecuteAndPrintObject::SetInputObjectName

AcExecuteAndPrintObject::SetOutputObjectName

AcExecuteAndPrintObject:: SetOutputObjectVersionName

AcExecuteAndPrintObject::SetPrinterName

AcExecuteAndPrintObject::SetPriority

AcExecuteAndPrintObject::SetRequestOptions

AcExecuteAndPrintObject::SetSchedule

AcExecuteAndPrintObject::SetValuesObjectID

AcExecuteAndPrintObject::SetValuesObjectName


AcExecuteAndPrintObject::GetRequestID

Returns the ID of the request.

Syntax

RWCollectableString GetRequestID() const


AcExecuteAndPrintObject::SetBundledFlag

Sets a condition that packages the data with the report item for viewing outside the scope of the database.

Syntax

void SetBundledFlag(Boolean flag)

flag

Set to TRUE to bundle the output object with the input object.

Description

When the ROX is bundled with the ROI, you do not need access to a database to view the report. Bundling an ROX with its ROI means that the data is bundled with the report. Bundling ensures that you can view the report outside of the Actuate system because the report does not require access to a database for viewing. You can distribute the report items to clients who don't have the database, but need to view the report.

Bundled reports are displayed only after the Factory completes their generation.

Bundling is applicable on the server as well as the client.


AcExecuteAndPrintObject::SetInputObjectID

Specifies by ID the target object for executing the request.

Syntax

void SetInputObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object.

Description

There are two ways to specify the input object: by ID or by name. Specify either the name or the ID of the object, not both. If you do specify both, the server uses the last one specified when it sends the request. For more information, see Input and output objects.


AcExecuteAndPrintObject::SetInputObjectName

Specifies by name and version, the target object, ROX, or Basic file for executing the request.

Syntax

void SetInputObjectName(const RWCollectableString& object_name,
AcVersionType version_type=AC_VERSION_LATEST,
unsigned long version_number= object_name)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path

version_type

The version of a report object. By default, the latest version of the object is used. version_type is an AcVersionType, which defines the following enumerated constants:

Value	Meaning
AC_VERSION_LATEST	The most recent version of the object, which is the default version type.
AC_VERSION_LATEST_ DEVELOPMENT	The version that has been flagged by a call to SetDevelopmentStatus as a development version.
AC_VERSION_LATEST_ RELEASED	The version that has been flagged by a call to SetDevelopmentStatus as a released version.
AC_VERSION_OLDEST	The initial version of the object.
AC_VERSION_SPECIFIC	Use with version_number to specify a particular version of the object.
version_number

A number that augments a file name to guarantee the uniqueness of file names for all versions of a report object. Use the version_number with a version_type parameter as shown in the following table:

Version_number	Parameter
zero	AC_VERSION_LATEST or AC_VERSION_OLDEST
nonzero	AC_VERSION_SPECIFIC
any number	AC_VERSION_LATEST_DEVELOPMENT or AC_VERSION_LATEST_RELEASED
Description

There are two ways to specify the input object: by ID or name. Specify either the name or the ID of the object, not both. The last specified of the two is the one used when a request is sent. For more information, see Referring to files--Windows environment.


AcExecuteAndPrintObject::SetOutputObjectName

Specifies the name of the output report instance for this request.

Syntax

void SetOutputObjectName(const RWCollectableString& object_name, RWBoolean version = FALSE)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path

version

A Boolean value specifying whether or not to create a new version of the object as the result of this request. If version is TRUE, and the object already exists, the server creates a new version of the object. If version is FALSE, and if a version of the object already exists and has no dependents, it is overwritten. Some report files depend on the existence of others. An .ROI and .ROV depend on an .ROX.

Description

The function identifies, by name, the object to use for output by this request. For example, the function might specify the name of an ROI file that results from execution of the request. For more information, see Referring to files--Windows environmentand Input and output objects.


AcExecuteAndPrintObject:: SetOutputObjectVersionName

Specifies the version name to be set on the output object created by this request.

Syntax

void SetOutputObjectVersionName(const RWCollectableString& version_name)

version_name

The version name of the output object.


AcExecuteAndPrintObject::SetPrinterName

Example

Sets the name of the printer that will print the object after it executes. For more information, see Referring to files--Windows environment.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer. Strings in the source code specifying the printer take double backslashes, \\. The first backslash is the escape character.


Example

In the Windows environment, name the printer this way:

AcExecuteAndPrintObject EandPO;

EandPO.SetPrinterName("\\\\Machine\\HP LASERJET IIP");


AcExecuteAndPrintObject::SetPriority

Specifies the scheduling precedence for running reports.

Syntax

void SetPriority(int priority)

priority

An integer 0-1000, the limit imposed by the Navigator's Requester dialog box, which sets high, medium, or low priority.


AcExecuteAndPrintObject::SetRequestOptions

Example   See also

Sets objects as options to be used with this request. The options are specified as a list of AcProperty objects.

Syntax

void SetRequestOptions(const RWOrdered& request_options)

request_options

The request options, a list of properties.

Description

The parameter for this function is a nested list of properties. The following table describes the parameter, showing the two types of top level properties at the top of the nested list and the request level list that each of the types can contain:

Top level property	Request level property list
property name = AC_REQUEST_OUTPUT_ OBJECT_PRIVILEGES
property value =  property list	name = Role ID or User ID
	semantic type = AC_SEMANTIC_ TYPE_ROLE or AC_SEMANTIC_ TYPE_USER
	value = a string list specifying read, write, and other privileges. For more information, seeAcAddPrivilegeToUser::SetPrivilegeType
property name = AC_PRINTER_REQUEST_ OPTIONS
property value = property list	name = one of the printer option property names. For more information, see AcGetPrinterInformation::GetPrinterOptions
	value = one of the printer option property values.
There are two top level properties:

•	AC_REQUEST_OUTPUT_OBJECT_PRIVILEGES specifies user or role privileges for the output report when requesting report execution. The value of the top level property is a property list. The name of each property in the list is a role ID or user ID, depending on the semantic type of the property. The semantic type of the property must be either AC_SEMANTIC_TYPE_ROLE or AC_SEMANTIC_TYPE_USER. The value of each property is an ordered list of strings specifying all the privilege relationships between the user or role named in the property and the generated report.

•	AC_PRINTER_REQUEST_OPTIONS specifies settable printer options. The value of the top level property is a property list. The name of each property in the list is a printer option name and the value is the option setting.


Example

This example builds a property list to request three printed and collated copies of the report, forecast in the Eastern Region folder of the Report Encyclopedia.

RWCollectableString inputObject = "/Eastern Region/forecast.rox";

RWCollectableString valuesObject = "/Eastern Region/forecast.rov";

RWCollectableString outputObject = "/Eastern Region/forecast.roi";

RWCollectableString printerName = "\\\\lahaina\\HP LASERJET IIP";

AcExecuteAndPrintObject printExecObj;

printExecObj.SetInputObjectName(inputObject);

printExecObj.SetOutputObjectName(outputObject,TRUE);

printExecObj.SetValuesObjectName(valuesObject);

printExecObj.SetPrinterName("monster");

printExecObj.SetPriority(500); // Medium priority

// Create a list and add two properties specifying number

// of copies to print and collate

RWOrdered list;

list.clearAndDestroy();

AcProperty property;

property.SetName(AC_PRINTER_OPTION_COPIES);

property.SetIntegerValue(3);

list.append(new AcProperty(property));

property.SetName(AC_PRINTER_OPTION_COLLATE);

property.SetIntegerValue(1);

list.append(new AcProperty(property));

// Create a top level property object

AcProperty printerOptionsProperty;

// Name it AC_PRINTER_REQUEST_OPTIONS

printerOptionsProperty.SetName(AC_PRINTER_REQUEST_OPTIONS);

// Make the value of the top level property object the list of printer properties

printerOptionsProperty.SetPropertyListValue(list);

list.clearAndDestroy();

// Add the top level property to the list

list.append(new AcProperty(printerOptionsProperty));

// Set the printer options in the list to be used with this request

printExecObj.SetRequestOptions(list);

list.clearAndDestroy();

m_sendStatus =m_connection->SendRequest(printExecObj, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  cout << " Function executed succesfully" << endl;

)


See also

AcAddPrivilegeToUser::SetPrivilegeType

AcGetPrinterInformation::GetPrinterOptions


AcExecuteAndPrintObject::SetSchedule

Example   See also

Sets the repeat schedule of this request.

Syntax

void SetSchedule(const RWOrdered& schedule)

schedule

The repeat schedule. This is a list of AcSchedule objects that specify the schedule of this request.


Example

This example shows how to schedule a report to execute and print in one minute and again at the same time every day until December 31, 1999.

AcExecuteAndPrintObject eAndp;

eAndp.SetInputObjectName("/Western Region/forecast.rox");

eAndp.SetValuesObjectName("/Western Region/forecast.rov");

eAndp.SetOutputObjectName("/Western Region/forecast.roi",TRUE);

eAndp.SetPrinterName("\\\\lahaina\\HP LASERJET IIP");

//m_sendStatus =m_connection->SendRequest(  eAndp, m_timeout);

 AcSchedule schedule;

// Uses today's date

RWCollectableDate startDate;

schedule.SetStartDate(startDate);

// When this schedule should end--31st Dec, 1999

RWDate endDate(31,12,99);

schedule.SetEndDate(endDate);

// Max duration of this schedule; if duration time expired, abort this operation

// What time this schedule is started today

RWTime startTime = RWTime::now() + 60;

schedule.AddAbsoluteTime(startTime);

RWOrdered schedules;

schedules.append(&schedule);

eAndp.SetSchedule(schedules);

eAndp.SetPriority(3); // Low priority

m_sendStatus =m_connection->SendRequest(eAndp, m_timeout);


See also

AcSchedule


AcExecuteAndPrintObject::SetValuesObjectID

Specifies by ID the ROV file that the execute request uses to obtain database usernames, passwords, and other execution options.

Syntax

void SetValuesObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object. Only objects stored by persistent object servers have IDs. Other objects can only be identified by their names or contents.


AcExecuteAndPrintObject::SetValuesObjectName

Specifies by name the ROV object that the execute request uses to obtain database usernames, passwords, and other execution options. For more information, see Referring to files--Windows environment.

Syntax

void SetValuesObjectName(const RWCollectableString& object_name)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path.


AcExecuteObject

See also   Member functions of AcExecuteObject

Creates a message that requests executing the accompanying object.

Description

This function returns before there is time for the server to execute the ROX, so you have to wait for a while to see the processed report notice in the Completed folder. Use the request ID returned by the message to get the status and results of the request to execute the object.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetRequestID	Returns the ID of the request.
SetBundledFlag	Use this function to bundle two objects, such as an ROI and ROX.
SetInputObjectID	Specifies by ID the target object for executing the request.
SetInputObjectName	Specifies by name and version, the target object, ROX, or Basic file, for executing the request.
SetOutputObjectName	Specifies the output object name for this request.
SetOutputObjectVersionName	Specifies the version name to be set on the output object created by this request.
SetPriority	Specifies the scheduling precedence for running the reports associated with this request.
SetRequestOptions	Sets options, AcProperty objects, to be used with this request.
SetSchedule	Sets the repeat schedule of the request.
SetValuesObjectID	Specifies by ID the values object for getting database usernames, passwords, and other execution options.
SetValuesObjectName	Specifies by name the values object for getting database usernames, passwords, and other execution options.


See also

AcExecuteAndPrintObject


Member functions of AcExecuteObject

AcExecuteObject::GetRequestID

AcExecuteObject::SetBundledFlag

AcExecuteObject::SetInputObjectID

AcExecuteObject::SetInputObjectName

AcExecuteObject::SetOutputObjectName

AcExecuteObject:: SetOutputObjectVersionName

AcExecuteObject::SetPriority

AcExecuteObject::SetRequestOptions

AcExecuteObject::SetSchedule

AcExecuteObject::SetValuesObjectID

AcExecuteObject::SetValuesObjectName


AcExecuteObject::GetRequestID

Returns the ID of the request.

Syntax

RWCollectableString GetRequestID() const


AcExecuteObject::SetBundledFlag

Sets a condition that packages the data with the report item for viewing outside the scope of the database.

Syntax

void SetBundledFlag(Boolean flag)

flag

Set to TRUE to bundle the output object with the input object.

Description

When the ROX is bundled with the ROI, you do not need access to a database to view the report. Bundling an ROX with its ROI means that the data is bundled with the report. Bundling ensures that you can view the report outside of the Actuate system because the report does not require access to a database for viewing. You can distribute the report items to clients who don't have the database, but need to view the report.

Bundled reports are displayed only after the Factory completes their generation.

Bundling is applicable on the server as well as the client.


AcExecuteObject::SetInputObjectID

Specifies by ID the target object for executing the request.

Syntax

void SetInputObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object.

Description

There are two ways to specify the input object: by ID or by name. Specify either the name or the ID of the object, not both. If you do specify both, the server uses the last one specified when it sends the request. For more information, see Input and output objects.


AcExecuteObject::SetInputObjectName

Specifies by name and version, the target object, ROX, or Basic file for executing the request.

Syntax

void SetInputObjectName(const RWCollectableString& object_name,
AcVersionType version_type=AC_VERSION_LATEST,
unsigned long version_number= object_name)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path

version_type

The version of a report object. By default, the latest version of the object is used. version_type is an AcVersionType, which defines the following enumerated constants:

Value	Meaning
AC_VERSION_LATEST	The most recent version of the object, which is the default version type.
AC_VERSION_LATEST_ DEVELOPMENT	The version that has been flagged by a call to SetDevelopmentStatus as a development version.
AC_VERSION_LATEST_ RELEASED	The version that has been flagged by a call to SetDevelopmentStatus as a released version.
AC_VERSION_OLDEST	The initial version of the object.
AC_VERSION_SPECIFIC	Use with version_number to specify a particular version of the object.
version_number

A number that augments a file name to guarantee the uniqueness of file names for all versions of a report object. Use the version_number with a version_type parameter as shown in the following table:

Version_number	Parameter
zero	AC_VERSION_LATEST or AC_VERSION_OLDEST
nonzero	AC_VERSION_SPECIFIC
any number	AC_VERSION_LATEST_DEVELOPMENT or AC_VERSION_LATEST_RELEASED
Description

There are two ways to specify the input object: by ID or name. Specify either the name or the ID of the object, not both. The last specified of the two is the one used when a request is sent. For more information, see Referring to files--Windows environment.


AcExecuteObject::SetOutputObjectName

Specifies the name of the output report instance for this request.

Syntax

void SetOutputObjectName(const RWCollectableString& object_name, RWBoolean version = FALSE)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path

version

A Boolean value specifying whether or not to create a new version of the object as the result of this request. If version is TRUE, and the object already exists, the server creates a new version of the object. If version is FALSE, and if a version of the object already exists and has no dependents, it is overwritten. Some report files depend on the existence of others. An .ROI and .ROV depend on an .ROX.

Description

The function identifies, by name, the object to use for output by this request. For example, the function might specify the name of an ROI file that results from execution of the request. For more information, see Referring to files--Windows environmentand Input and output objects.


AcExecuteObject:: SetOutputObjectVersionName

Specifies the version name to be set on the output object created by this request.

Syntax

void SetOutputObjectVersionName(const RWCollectableString& version_name)

version_name

The version name of the output object.


AcExecuteObject::SetPriority

Specifies the scheduling precedence for running reports.

Syntax

void SetPriority(int priority)

priority

An integer 0-1000, the limit imposed by the Navigator's Requester dialog box, which sets high, medium, or low priority.


AcExecuteObject::SetRequestOptions

Sets objects as options to be used with this request. The options are specified as a list of AcProperty objects.

Syntax

void SetRequestOptions(const RWOrdered& request_options)

request_options

The request options, a list of properties.

Description

The parameter for this function is a nested list of properties. The following table describes the parameter, showing the two types of top level properties at the top of the nested list and the request level list that each of the types can contain:

Top level property	Request level property list
property name = AC_REQUEST_OUTPUT_ OBJECT_PRIVILEGES
property value =  property list	name = Role ID or User ID
	semantic type = AC_SEMANTIC_ TYPE_ROLE or AC_SEMANTIC_ TYPE_USER
	value = a string list specifying read, write, and other privileges. For more information, seeAcAddPrivilegeToUser::SetPrivilegeType
AC_REQUEST_OUTPUT_OBJECT_PRIVILEGES specifies user or role privileges for the output report when requesting report execution. The value of the top level property is a property list. The name of each property in the list is a role ID or user ID, depending on the semantic type of the property. The semantic type of the property must be either AC_SEMANTIC_TYPE_ROLE or AC_SEMANTIC_TYPE_USER. The value of each property is an ordered list of strings specifying all the privilege relationships between the user or role named in the property and the generated report.


AcExecuteObject::SetSchedule

See also

Sets the repeat schedule of this request.

Syntax

void SetSchedule(const RWOrdered& schedule)

schedule

The repeat schedule. This is a list of AcSchedule objects that specify the schedule of this request.


See also

AcSchedule


AcExecuteObject::SetValuesObjectID

Specifies by ID the ROV file that the execute request uses to obtain database usernames, passwords, and other execution options.

Syntax

void SetValuesObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object. Only objects stored by persistent object servers have IDs. Other objects can only be identified by their names or contents.


AcExecuteObject::SetValuesObjectName

Specifies by name the ROV object that the execute request uses to obtain database usernames, passwords, and other execution options. For more information, see Referring to files--Windows environment.

Syntax

void SetValuesObjectName(const RWCollectableString& object_name)

object_name

The user-defined, fully qualified path name of the object. Only objects stored by persistent object servers have hierarchical paths. Other objects, such as users, are stored in the administration server and have names, but no hierarchical path.


AcGetChannelCompletedRequests

Member functions of AcGetChannelCompletedRequests

Creates a message to get the IDs of requests completed by the Report Server for the specified channel. For more information, see egclient in the examples directory of the Report Server API.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetChannelName	Specifies the channel name to query for completed requests.
GetRequestIDs	Returns the identifiers for the requests.
SetRequestNameFilter	Specifies the names of the requests that the caller is interested in.
GetRequestNameFilter	Gets the names of the requests that the caller is interested in.


Member functions of AcGetChannelCompletedRequests

AcGetChannelCompletedRequests:: SetChannelName

AcGetChannelCompletedRequests:: GetRequestIDs

AcGetChannelCompletedRequests:: SetRequestNameFilter

AcGetChannelCompletedRequests:: GetRequestNameFilter


AcGetChannelCompletedRequests:: SetChannelName

Specifies the channel name to query for completed requests.

Syntax

void SetChannelName(const RWCollectableString& channel_name)

channel_name

The text string representing the name of the channel.


AcGetChannelCompletedRequests:: GetRequestIDs

Returns the request IDs.

Syntax

RWOrdered GetRequestIDs() const


AcGetChannelCompletedRequests:: SetRequestNameFilter

Specifies the names of the requests that the caller is interested in.

Syntax

void SetRequestNameFilter(const RWOrdered& request_names)

request_names

The names of the requests.


AcGetChannelCompletedRequests:: GetRequestNameFilter

Gets the names of the requests that the caller is interested in.

Syntax

RWOrdered GetRequestNameFilter() const


AcGetChannelProperties

Member functions of AcGetChannelProperties

Represents a request to access the properties of a channel for this request.

Constructor

This class has default and copy constructors.

Description

The following table lists the accessible channel properties

Name	Description
AC_CHANNEL_ITEM_EXPIRATION	Unsigned integer value representing the expiration time in seconds an item remains on this channel before it is removed.
AC_CHANNEL_SUBSCRIPTION_LIST	The channels that users have privileges to subscribe to.
AC_CHANNEL_SMALL_ICON_URL	The URL of the small custom icon for the current channel.
AC_CHANNEL_LARGE_ICON_URL	The URL of the large custom icon for the current channel.
AC_CHANNEL_POLLING_INTERVAL	The number of seconds that elapses until the next time the Report Server refreshes the contents of the channel.
AC_CHANNEL_COMMENT	A description of the channel.
:

For more information, see egclient in the examples directory of the Report Server API.

Public member functions

Member function	Description
GetChannelProperties	Returns the properties of a channel for this request.


Member functions of AcGetChannelProperties

AcGetChannelProperties::GetChannelProperties


AcGetChannelProperties::GetChannelProperties

Returns the properties of a channel for this request.

Syntax

RWOrdered GetChannelProperties() const;


AcGetChannelNames

Member functions of AcGetChannelNames

Creates a message for the administration server requesting the channel names that the requesting user is allowed to read. For more information, see egclient in the examples directory of the Report Server API.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetChannelNames	Returns the names of all channels.


Member functions of AcGetChannelNames

AcGetChannelNames::GetChannelNames


AcGetChannelNames::GetChannelNames

Returns the names of all of the channels that the requesting user is allowed to read.

Syntax

RWOrdered GetChannelNames() const


AcGetDataForRoles

Member functions of AcGetDataForRoles

Retrieves role names and roles of a role.

Description

Creates a message that queries the administration server for the names of roles and the roles inherited by those roles. The returned data is an ordered list of AcProperties, one for each role. Each AcProperty contains a property list with two elements: the name of the role and an AcProperty with a string list containing all the superior roles for that role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleNames	Sets a list of roles for which you want data.
GetRoleData	Returns a list role names inherited by either the specified roles or all roles.


Member functions of AcGetDataForRoles

AcGetDataForRoles::SetRoleNames

AcGetDataForRoles::GetRoleData


AcGetDataForRoles::SetRoleNames

Sets the list of role names to query for inherited roles.

Syntax

void SetRoleNames(RWOrdered& names)

names

A list of valid role names on the administration server.


AcGetDataForRoles::GetRoleData

Gets data for the specified roles or all roles.

Syntax

RWOrdered GetRoleData() const

Description

Returns data for the named roles or, if role names are not set, returns data for all roles.


AcGetEventInformation

Member functions of AcGetEventInformation

Creates a message that gets information about an event.

Description

This function gets information that is contained in the event object to describe an event. Currently, one type of event is supported: object operation completed, specified as the character string "Operation Status".

Constructor

This class has a default and copy constructor.

Public member functions

Member function	Description
SetEventType	Passes the string "Operation Status".
GetEventInformation	Returns a list of AcProperty objects with event information.


Member functions of AcGetEventInformation

AcGetEventInformation::SetEventType

AcGetEventInformation::GetEventInformation


AcGetEventInformation::SetEventType

Sets the event type to "Operation Status" to indicate that the object operation completed.

Syntafx

void SetEventType(const RWCollectableString& event_type)

event_type

The event type.


AcGetEventInformation::GetEventInformation

Returns a list of AcProperty objects that contain the event information.

Syntax

RWOrdered GetEventInformation() const

Description

The name of the element in the property list is the name of the information, currently, the name of the message that transports the event.


AcGetEventTypes

Member functions of AcGetEventTypes

Creates a message for the administration server requesting certain events.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetEventTypes	Returns event types (currently just "Operation Status"), a list of strings.


Member functions of AcGetEventTypes

AcGetEventTypes::GetEventTypes


AcGetEventTypes::GetEventTypes

Returns a list of strings containing the event types. Currently the only supported event type is "Operation Status".

Syntax

RWOrdered GetEventTypes() const


AcGetGroupNames

Example   Member functions of AcGetGroupNames

Represents a message to get the names of groups managed by the administration server.

Description

Creates a message that queries the administration server for the names of all existing groups. The server returns the names in an ordered list. Client applications can connect to the server as any user to make this query.

Constructor

This class has default and copy constructors only.

Public member function

Member function	Description
GetGroupNames	Gets a list of all group names.


Example

The following example shows how to get a list of group names from the administration server. This code assumes a connection to the server called m_connection already exists.

RWOrdered groups;

int m_timeout=100000000;

AcGetGroupNames getGroupsMsg;

m_sendStatus =m_connection->SendRequest(getGroupsMsg, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

groups = getGroupsMsg.GetGroupNames();

}


Member functions of AcGetGroupNames

AcGetGroupNames::GetGroupNames


AcGetGroupNames::GetGroupNames

Gets a list of all group names.

Syntax

RWOrdered GetGroupNames() const

Description

This function returns an ordered list of all group names. Call this function after sending a request to get group names.


AcGetGroupOwner

Member functions of AcGetGroupOwner

Represents a message to identify the group's owner.

Description

Creates a message that requests the name of a group's owner. Knowing the owner is an important aspect of managing groups because the group owner generally controls the membership.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetGroupName	Sets the group name to check.
GetUserName	Gets the name of the user that owns the group.


Member functions of AcGetGroupOwner

AcGetGroupOwner::SetGroupName

AcGetGroupOwner::GetUserName


AcGetGroupOwner::SetGroupName

Sets the group name to check for ownership.

Syntax

void SetGroupName(const RWCollectableString& name)

name

A valid group name on the administration server.


AcGetGroupOwner::GetUserName

Gets the name of the user that owns the group.

Syntax

RWCollectableString GetUserName() const

Description

This function returns the owner of the group. Call this function after sending a request to get the group owner.


AcGetGroupUserNames

Example   Member functions of AcGetGroupUserNames

Represents a message to identify users in a certain group.

Description

Creates a message that queries the server for a list of all the users in a specific group. Checking the group membership is a way of determining if users with common notification needs are included in the group. Client applications can connect to the server with any user name to make this query.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetGroupName	Sets the name of the group to query for users.
GetUserNames	Returns a list of user names.


Example

The following example shows how to retrieve the names of all members in a group called Marketing. This code assumes a server connection called m_connection already exists.

RWCollectableString groupName="Marketing";

RWOrdered users;

int m_timeout=100000000;

AcGetGroupUserNames getGroupUsersMsg;

getGroupUsersMsg.SetGroupName(groupName);

m_sendStatus =m_connection->SendRequest(getGroupUsersMsg,

m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  users = getGroupUsersMsg.GetUserNames();

  }


Member functions of AcGetGroupUserNames

AcGetGroupUserNames::SetGroupName

AcGetGroupUserNames::GetUserNames


AcGetGroupUserNames::SetGroupName

Sets the name of the group to query for users.

Syntax

void SetGroupName(const RWCollectableString& group_name)

group_name

A valid group name on the administration server.


AcGetGroupUserNames::GetUserNames

Gets a list of user names.

Syntax

RWOrdered GetUserNames() const

Description

This function returns an ordered list of user names. Call this function after sending a request to get group user names.


AcGetHighestNumberOfLogins

Member functions of AcGetHighestNumberOfLogins

Represents a request for getting the highest number of concurrent logins the Report Server has ever had.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetNumberOfLogins	Returns the highest number of concurrent logins.


Member functions of AcGetHighestNumberOfLogins

AcGetHighestNumberOfLogins:: GetNumberOfLogins


AcGetHighestNumberOfLogins:: GetNumberOfLogins

Returns the highest number of concurrent logins.

Syntax

unsigned long GetNumberOfLogins() const


AcGetIDFromName

Example   Member functions of AcGetIDFromName

Represents a message to find the unique ID of an object given its name.

Description

Creates a message that queries the administration server for the ID associated with a specific name. The name can be any valid user, group, role, or channel name that is used inside the Encyclopedia to identify the object. You use the unique ID for constructing the following things: a user privilege template, which is stored in the user's preferences and some Administrator preferences that specify the maximum request priority for a user.

Constructor

This class has default and copy constructors only.


Example

The following example shows how to get the ID of a user named William. This code assumes that a server connection called m_connection already exists.

RWCollectableString user="William", id;

int m_timeout=100000000;

AcGetIDFromName getIDFromNameMsg;

getIDFromNameMsg.SetNameType(AcNameRequest::AC_USER);

getIDFromNameMsg.SetName(user);

m_sendStatus =m_connection->SendRequest(getIDFromNameMsg, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  id = getIDFromNameMsg.GetID();

  }

Public member functions

Member function	Description
SetNameType	Identifies the name as a user, role, or group type.
SetName	Sets the specific user, role, or group name for the query.
GetID	Gets the ID the server returned.


Member functions of AcGetIDFromName

AcGetIDFromName::SetNameType

AcGetIDFromName::SetName

AcGetIDFromName::GetID


AcGetIDFromName::SetNameType

Specifies the type name being translated.

Syntax

void SetNameType(AcNameRequest::AcNameType name_type)

name_type

The type of name for the query, as follows:

•	AcNameRequest::AC_USER

•	AcNameRequest::AC_ROLE

•	AcNameRequest::AC_GROUP

•	AcNameRequest::AC_CHANNEL


AcGetIDFromName::SetName

Sets the specific user, role, group, or channel name for the ID query.

Syntax

void SetName(const RWCollectableString& name)

name

A valid user, role, group or channel name on the administration server.


AcGetIDFromName::GetID

Gets the ID the server returned.

Syntax

RWCollectableString GetID() const

Description

This function returns the ID associated with the specified user, role, group, or channel. Call this function after sending the AcGetIDFromName object with a request using AcClientConnection::SendRequest.


AcGetLoginUsers

Example   Member functions of AcGetLoginUsers

Represents a request for getting the names of users who are currently logged in.

Constructor

This class has default and copy constructors.

Description

Creates a message to get the names of the users currently logged in. A user is logged in if their name is passed by the API to make a connection programmatically, or if they logged into the Report Encyclopedia.


Example

This example makes a connection to send the loginUsers message to get user names.

AcGetLoginUsers loginUsers;

m_sendStatus =m_connection->SendRequest(loginUsers, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

}

else {

RWOrdered loginUsersNames = loginUsers.GetUserNames();

// code to use loginUsersNames goes here

}

Public member functions

Member function	Description
GetUserNames	Returns the names of the logged in users.


Member functions of AcGetLoginUsers

AcGetLoginUsers::GetUserNames


AcGetLoginUsers::GetUserNames

Returns the names of the logged in users.

Syntax

RWOrdered GetUserNames() const

Description

This function returns the user names as an RWOrdered collection. Call RWOrdered::closeAndDestroy to delete the collection when you are finished using it.


AcGetNameFromID

Example   Member functions of AcGetNameFromID

Represents a message to find the name of an object given its ID.

Description

Creates a message that queries the administration server for the name associated with a specific ID. The ID can be associated with any valid user, group, or role. The server returns the name associated with the ID.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetNameType	Identifies the name as a user's, role's, or group's.
SetID	Sets the user, role, or group ID for the query.
GetName	Accesses the name of a user, role, or group.


Example

The following example shows how to use AcGetIDFromName to get the ID of a user named William. Use AcGetNameFromID the same way. This code assumes that a server connection called m_connection already exists.

RWCollectableString user="William", id;

int m_timeout=100000000;

AcGetIDFromName getIDFromNameMsg;

getIDFromNameMsg.SetNameType(AcNameRequest::AC_USER);

getIDFromNameMsg.SetName(user);

m_sendStatus =m_connection->SendRequest(getIDFromNameMsg, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  id = getIDFromNameMsg.GetID();

  }


Member functions of AcGetNameFromID

AcGetNameFromID::SetNameType

AcGetNameFromID::SetID

AcGetNameFromID::GetName


AcGetNameFromID::SetNameType

Identifies the name as a user, role, or group type.

Syntax

void SetNameType(AcNameRequest::AcNameType name_type)

name_type

The type of name for the query, as follows:

•	AcNameRequest::AC_USER

•	AcNameRequest::AC_ROLE

•	AcNameRequest::AC_GROUP


AcGetNameFromID::SetID

Sets the specific user, role, or group ID for the name query.

Syntax

void SetID(const RWCollectableString& id)

id

A text string representing the id.


AcGetNameFromID::GetName

Accesses the name of a user, role, or group.

Syntax

RWCollectableString GetName() const

Description

This function returns the user, role, or group name associated with the specified ID. Call this function after sending a request to get the name from the ID.


AcGetNumberOfUserLogins

Example   Member functions of AcGetNumberOfUserLogins

Determines the number of times the specified user is logged in.

Description

Creates a message that requests the number of times the given user logged in. Someone is logged in if their name is passed by the API to make a connection programmatically or if Actuate is running and they logged into the Report Encyclopedia.

Constructor

This class has a default constructor.

Public member functions

Member function	Description
SetUserName	Establishes the name of the user to query.
GetNumberOfLogins	Returns the number of times the user is logged in.


Example

This example makes a connection (logs into the Report Encyclopedia) as Administrator. A name of an AcGetNumberOfUserLogins object is set to Administrator. The message is sent to the server. The requested number of times the Administrator is logged in is displayed.

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcClientConnection  *m_connection;

AcClientConnection::AcConnectionStatus c_status;

RWCollectableString m_userName="Administrator", m_password="";

// Make connection to the server

m_connection = new AcClientConnection("","Haleakala",

m_userName,m_password);

c_status = m_connection->GetConnectionStatus();

AcGetNumberOfUserLogins noLoginUser;

noLoginUser.SetUserName(m_userName);

m_sendStatus=m_connection->SendRequest(noLoginUser, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

unsigned long number = noLoginUser.GetNumberOfLogins();

cout << " No of user Logins : " << (int)number << endl; }


Member functions of AcGetNumberOfUserLogins

AcGetNumberOfUserLogins::SetUserName

AcGetNumberOfUserLogins::GetNumberOfLogins


AcGetNumberOfUserLogins::SetUserName

Establishes the name of the user to query regarding the number of times they are logged into the Report Encyclopedia.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of the user.


AcGetNumberOfUserLogins::GetNumberOfLogins

Returns the number of times the user is logged into the Report Encyclopedia.

Syntax

unsigned long GetNumberOfLogins() const


AcGetObjectCompletedRequests

Example   See also   Member functions of AcGetObjectCompletedRequests

Creates a message to get the completed requests for an object.

Description

AcGetObjectCompletedRequests can retrieve the IDs of requests that were completed for a particular ROX. When requests are complete, a request appears in the Completed folder in the Report Encyclopedia.

Member functions of this class are not backward compatible with Server releases earlier than 3.0.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetRequestIDs	Returns the request IDs.
SetObjectID	Specifies the ID of the object to query.
SetObjectName	Specifies the name of the object to query.


Example

This example shows how to call the GetRequestID function to identify requests that are completed for the object called forecast.rox in the Report Encyclopedia.

int m_timeout=100000000;

AcGetObjectCompletedRequests compReqs;

compReqs.SetObjectName("/Western Region/forecast.rox");

m_sendStatus =m_connection->SendRequest(compReqs, m_timeout);

RWOrdered compIds = compReqs.GetRequestIDs();

cout << "Completed Requests  for object " << endl;

RWOrderedIterator l_iter((RWOrdered&) compIds);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

}


See also

AcGetUserCompletedRequests


Member functions of AcGetObjectCompletedRequests

AcGetObjectCompletedRequests::GetRequestIDs

AcGetObjectCompletedRequests::SetObjectID

AcGetObjectCompletedRequests::SetObjectName


AcGetObjectCompletedRequests::GetRequestIDs

Returns the IDs for the completed requests.

Syntax

RWOrdered GetRequestIDs()

Description

There are two ways to specify the object to query: by ID or by name. This function specifies the object to be retrieved by its ID. It returns a collection of the completed request ID's. Call RWOrdered:closeAndDestroy to delete the collection when you are finished using it.


AcGetObjectCompletedRequests::SetObjectID

Specifies by ID the object to query.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The global unique object ID.

Description

There are two ways to specify the object to query: by ID or by name. This function specifies the object by ID.


AcGetObjectCompletedRequests::SetObjectName

Specifies the name of the object to query.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object.

Description

There are two ways to specify the object to query: by ID or by name. This function specifies the object by name.


AcGetObjectPendingRequests

Example   Member functions of AcGetObjectPendingRequests

Creates a message to identify pending requests for an object.

Constructor

This class has default and copy constructors.

Description

Creates a message to get the IDs of the pending requests for the specified object. Pending requests are scheduled requests that are in the priority queue but not yet executed.

Public member functions

Member function	Description
GetRequestIDs	Returns the IDs of pending requests.
SetObject	Specifies the ID of the object to query.
SetObjectName	Specifies the name of the object to query.


Example

Given an object name this function gets its pending status. Not recommended for Server releases earlier than 3.0.

RWCollectableString = "/forecast.rox"

AcGetObjectPendingRequests pendReqs;

pendReqs.SetObjectName(objectName);

m_sendStatus =m_connection->SendRequest(pendReqs, m_timeout);

RWOrdered pendIds = pendReqs.GetRequestIDs();

cout << "Pending Requests  for object " << endl;

RWOrderedIterator l_iter((RWOrdered&) pendlds);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;


Member functions of AcGetObjectPendingRequests

AcGetObjectPendingRequests::GetRequestIDs

AcGetObjectPendingRequests::SetObjectID

AcGetObjectPendingRequests::SetObjectName


AcGetObjectPendingRequests::GetRequestIDs

Returns the IDs of pending requests for the specified object.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns IDs as an RWOrdered collection. Call RWOrdered::closeAndDestroy to delete the collection when you are finished using it.


AcGetObjectPendingRequests::SetObjectID

Specifies the ID of the object that may have pending requests to identify.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The global unique object ID.

Description

There are two ways to establish which object to query about pending requests, by ID or by name. This function uses the ID.


AcGetObjectPendingRequests::SetObjectName

Specifies the name of the object that may have pending requests to identify.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object.

Description

There are two ways to establish which object to query about pending requests, by ID or by name. This function uses the name.


AcGetObjectScheduleRequests

Example   Member functions of AcGetObjectScheduleRequests

Creates a message to get the IDs of the schedule requests corresponding to the specified object.

Constructor

This class has default and copy constructors.

Description

This class represents a request for getting the scheduled requests for an object. Schedules are stored in a repository that the request server reads at start-up. When it is time to execute a scheduled request, the request server places the request on the priority queues, which it runs in turn.

Public member functions

Member function	Description
GetRequestIDs	Returns the IDs of requests scheduled for an object.
SetObjectID	Specifies by ID the object to query regarding its scheduled requests.
SetObjectName	Specifies by name the object to query regarding its scheduled requests.


Example

To run an example of this class, add the following code to the end of requestObject Test 16 of egclient.

AcGetObjectScheduleRequests getreq;

  getreq.SetObjectName(inputObject);

  m_sendStatus = m_connection->SendRequest(getreq, m_timeout);

  RWOrdered reqlist = getreq.GetRequestIDs();

RWOrderedIterator l_iter((RWOrdered&) reqlist);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

}

reqlist.clearAndDestroy();


Member functions of AcGetObjectScheduleRequests

AcGetObjectScheduleRequests::GetRequestIDs

AcGetObjectScheduleRequests::SetObjectID

AcGetObjectScheduleRequests::SetObjectName


AcGetObjectScheduleRequests::GetRequestIDs

Returns the request IDs of requests scheduled for this object.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns request IDs scheduled for this object as an RWOrdered collection. Call RWOrdered::closeAndDestroy to delete the collection when you are finished using it.


AcGetObjectScheduleRequests::SetObjectID

Specifies the ID of the object to query regarding its scheduled requests.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The global unique object ID.

Description

There are two ways to specify the object to query about scheduled requests: by name or by ID. This function specifies the object by ID.


AcGetObjectScheduleRequests::SetObjectName

Specifies the name of the object to query regarding its scheduled requests.

Syntax

void SetObjectName(const RWCollectableString& object_name)

Description

There are two ways to specify the object to query about scheduled requests: by name or by ID. This function specifies the object by name.


AcGetPrinterInformation

Example   Member functions of AcGetPrinterInformation

Represents a message to get information about the printer, such as the manufacturer.

Description

Creates a message for the administration server requesting detailed information about the specified printer, such as its location and settings for printing multiple copies, landscape or portrait orientation, and so on.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetPrinterName	Sets the name of the printer with information to be accessed.
SetAttributeOptionsFlag	Specifies whether or not to return the list of attributes with the list of options.
GetPrinterAttributes	Returns a list of AcProperty objects that contain the fixed attributes of the printer.
GetPrinterOptions	Accesses printer options, a list of properties.


Example

The following example, from egclient, creates a getPrinterInfo object and sets the name of the printer:

AcGetPrinterInformation getPrinterInfo;

  getPrinterInfo.SetPrinterName("\\HP LaserJet IIP");

  getPrinterInfo.SetAttributeOptionsFlag(FALSE);

  m_sendStatus =m_connection->SendRequest(getPrinterInfo, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout <<" ----------Attributes ---------------------" << endl;

RWOrdered list =getPrinterInfo.GetPrinterAttributes();

// code goes here to display list; see egclient's printerTable, Test 3

list.clearAndDestroy();

cout <<" ----------Options ---------------------" << endl;

list=getPrinterInfo.GetPrinterOptions();

// code goes here to display list; see egclient's printerTable, Test 3

list.clearAndDestroy();

}


Member functions of AcGetPrinterInformation

AcGetPrinterInformation::SetPrinterName

AcGetPrinterInformation::SetAttributeOptionsFlag

AcGetPrinterInformation::GetPrinterAttributes

AcGetPrinterInformation::GetPrinterOptions


AcGetPrinterInformation::SetPrinterName

Sets the name of the printer with information to access.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer that you want information about. Pass a name such as "\\\\Lahaina\\HP LaserJet IIP", a network printer on machine Lahaina. The first backslash in a pair of backslashes is the escape character.


AcGetPrinterInformation::SetAttributeOptionsFlag

See also

Specifies whether to return the list of attributes with the list of options.

Syntax

void SetAttributeOptionsFlag(RWBoolean flag)

flag

TRUE (1) sets a flag to return the attributes and options. FALSE (0) sets a flag to return options only.

Description

Use this function to design GUIs for printer settings. The flag inhibits extraneous printer attributes (printer attributes with the same values as printer options) from being included in the list of options returned by AcGetPrinterInformation:: GetPrinterAttributes. Attributes must be set explicitly to be affected by this flag.

NT sets the printer attributes model name and location at the system level. UNIX does not manage these printer attributes, so you must set them explicitly through the Report Server API, Navigator, or other interface.


See also

AcExecuteAndPrintObject::SetRequestOptions

AcGetPrinterInformation::GetPrinterAttributes


AcGetPrinterInformation::GetPrinterAttributes

Example

Returns a list of AcProperty objects that contain the fixed attributes of the printer.

Syntax

RWOrdered GetPrinterAttributes() const

Description

This function returns the printer attributes as an ordered list. Delete the contents of the list when you are finished using it. The following describes the property names and the valid values for each of the attributes:

Attribute	Property name	Value type
Printer Manufacturer	AC_PRINTER_ATTRIBUTE_ MANUFACTURER	string
Printer Model	AC_PRINTER_ATTRIBUTE_ MODEL	string
Printer Brand Name	AC_PRINTER_ATTRIBUTE_ DESCRIPTION	string
Printer Brand Name	AC_PRINTER_ATRRIBUTE_ LOCATION	string


Example

The following output shows the attributes returned by this function. This output is from the egclient example in AcGetPrinterInformation.

C:\Actuate\Server\rsapi\NT\examples>egclientD -CprinterTable -T3 -1"\\Lahaina\HP

LaserJet IIP" -2TRUE -Mhaleakala -UAdministrator
Connected To Server With  Status  : 0
 ----------Attributes ---------------------
BEGIN_PROPERTY
      __AC_PRINTER_ATTRIBUTE_MANUFACTURER
HP
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_ATTRIBUTE_MODEL
HP LaserJet IIP
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_ATTRIBUTE_DESCRIPTION
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_ATTRIBUTE_LOCATION
END_PROPERTY


AcGetPrinterInformation::GetPrinterOptions

Example

Accesses printer options, a list of properties.

Syntax

RWOrdered GetPrinterOptions() const

Description

Returns a list of AcProperty objects that contain the settable printer options. The name of each element is the name of the option. The value of the element is the list of choices for the option.

The first value in a list of choices is the default value. The list returned by this member function can be used as the input list for any member function that specifies print options. If there is no property returned for a particular option, the printer does not support the option.

UNIX platform considerations

These options apply to UNIX only:

•	AC_PRINTER_ATTRIBUTE_MODEL

•	AC_PRINTER_ATTRIBUTE_DESCRIPTION

•	AC_PRINTER_ATTRIBUTE_LOCATION

On the NT platform, the system manages these options.

When an option property name has the same name as an attribute, you must specify the option through the system level defaults using the AcSetPrinterOptionDefaults message. The default value of the printer option is the one bearing the same name as the attribute, which is returned by AcGetPrinterInformation::GetPrinterAttributes. When you are finished using the property list returned by GetPrinterAttributes, delete its contents.

Property names

The following table describes the property names listed in util/msgpname.h and the valid values for each of the options:

Printer option	Property name	Value type
Model - UNIX Only	AC_PRINTER_ATTRIBUTE_ MODEL	String list: model names valid for UNIX. The first in the list is the default.
Brand Name- UNIX Only	AC_PRINTER_ATTRIBUTE_ DESCRIPTION	String.
Location- UNIX Only	AC_PRINTER_ATRRIBUTE_ LOCATION	String.
Print to File	AC_PRINTER_OPTION_ PRINT_TO_FILE	String, file name, such as "myfile.ps".
Paper Length	AC_PRINTER_OPTION_ PAPER_LENGTH	Integer. Specifies paper size in .1 mm.
Page Range	AC_PRINTER_OPTION_ PAGE_RANGE	Integer. The page range expressed as a single integer or two integers separated by either a comma or a hyphen. For example, 1 or 1,2 or 1-3.
Paper Width	AC_PRINTER_OPTION_ PAPER_WIDTH	Integer. Specifies paper size in .1 mm.
Form Name	AC_PRINTER_OPTION_ FORMNAME	Integer. See valid values for Windows 95/NT following this table.
Orientation	AC_PRINTER_OPTION_ ORIENTATION	String list, for example: ("LANDSCAPE", "PORTRAIT"). The first in the list is the default, others are valid orientation options.
Scale	AC_PRINTER_OPTION_ SCALE	Integer.
Resolution	AC_PRINTER_OPTION_ RESOLUTION	String list. The first in the list is the default; others are valid resolution options.
Copies	AC_PRINTER_OPTION_ COPIES	Integer.
Page Size	AC_PRINTER_OPTION_ PAGE_SIZE	String list. The first in the list is the default, others are valid page size options.
Paper Tray	AC_PRINTER_OPTION_ PAPER_TRAY	String list; The first in the list is the default; others are valid paper tray options.
Color	AC_PRINTER_OPTION_ COLOR	RWBoolean.
Duplex	AC_PRINTER_OPTION_ DUPLEX	String list, for example: ("SIMPLE", "HORIZONTAL", "VERTICAL"). The first in the list is the default, others are valid duplex options. Not supported by XPrinter.
Collate	AC_PRINTER_OPTION_ COLLATE	RWBoolean.
AC_PRINTER_OPTION_FORMNAME

With this printer option, you can specify various paper sizes. Set the option to 0 for the paper size specified by AC_PRINTER_OPTION_PAPER_WIDTH and _LENGTH. Set AC_PRINTER_OPTION_FORMNAME to one of the following values:

Value	Meaning
DMPAPER_FIRST	Use Custom paper settings
DMPAPER_LETTER	Letter, 8 1/2- by 11-inches
DMPAPER_LEGAL	Legal, 8 1/2- by 14-inches
DMPAPER_A4	A4 Sheet, 210- by 297-millimeters
DMPAPER_CSHEET	C Sheet, 17- by 22-inches
DMPAPER_DSHEET	D Sheet, 22- by 34-inches
DMPAPER_ESHEET	E Sheet, 34- by 44-inches
DMPAPER_LETTERSMALL	Letter Small, 8 1/2- by 11-inches
DMPAPER_TABLOID	Tabloid, 11- by 17-inches
DMPAPER_LEDGER	Ledger, 17- by 11-inches
DMPAPER_STATEMENT	Statement, 5 1/2- by 8 1/2-inches
DMPAPER_EXECUTIVE	Executive, 7 1/4- by 10 1/2-inches
DMPAPER_A3	A3 sheet, 297- by 420-millimeters
DMPAPER_A4SMALL	A4 small sheet, 210- by 297-millimeters
DMPAPER_A5	A5 sheet, 148- by 210-millimeters
DMPAPER_B4	B4 sheet, 250- by 354-millimeters
DMPAPER_B5	B5 sheet, 182- by 257-millimeter paper
DMPAPER_FOLIO	Folio, 8 1/2- by 13-inch paper
DMPAPER_QUARTO	Quarto, 215- by 275-millimeter paper
DMPAPER_10X14	10- by 14-inch sheet
DMPAPER_11X17	11- by 17-inch sheet
DMPAPER_NOTE	Note, 8 1/2- by 11-inches
DMPAPER_ENV_9	#9 Envelope, 3 7/8- by 8 7/8-inches
DMPAPER_ENV_10	#10 Envelope, 4 1/8- by 9 1/2-inches
DMPAPER_ENV_11	#11 Envelope, 4 1/2- by 10 3/8-inches
DMPAPER_ENV_12	#12 Envelope, 4 3/4- by 11-inches
DMPAPER_ENV_14	#14 Envelope, 5- by 11 1/2-inches
DMPAPER_ENV_DL	DL Envelope, 110- by 220-millimeters
DMPAPER_ENV_C5	C5 Envelope, 162- by 229-millimeters
DMPAPER_ENV_C3	C3 Envelope, 324- by 458-millimeters
DMPAPER_ENV_C4	C4 Envelope, 229- by 324-millimeters
DMPAPER_ENV_C6	C6 Envelope, 114- by 162-millimeters
DMPAPER_ENV_C65	C65 Envelope, 114- by 229-millimeters
DMPAPER_ENV_B4	B4 Envelope, 250- by 353-millimeters
DMPAPER_ENV_B5	B5 Envelope, 176- by 250-millimeters
DMPAPER_ENV_B6	B6 Envelope, 176- by 125-millimeters
DMPAPER_ENV_ITALY	Italy Envelope, 110- by 230-millimeters
DMPAPER_ENV_MONARCH	Monarch Envelope, 3 7/8- by 7 1/2-inches
DMPAPER_ENV_PERSONAL	6 3/4 Envelope, 3 5/8- by 6 1/2-inches
DMPAPER_FANFOLD_US	US Std Fanfold, 14 7/8- by 11-inches
DMPAPER_FANFOLD_STD_GERMAN	German Std Fanfold, 8 1/2- by 12-inches
DMPAPER_FANFOLD_LGL_GERMAN	German Legal Fanfold, 8 1/2- by 13-inches


Example

The following output shows the options returned by this function. This output is from the egclient example in AcGetPrinterInformation.

----------Options ---------------------

BEGIN_PROPERTY
      __AC_PRINTER_OPTION_ORIENTATION
      PORTRAIT
      LANDSCAPE
      AUTO
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_OPTION_PAGE_SIZE
      Letter 8 1/2 x 11 in
      Letter Small 8 1/2 x 11 in
      Legal 8 1/2 x 14 in
      Executive 7 1/2 x 10 in
      A4 210 x 297 mm
      A4 Small 210 x 297 mm
      Note 8 1/2 x 11 in
      Envelope #10 4 1/8 x 9 1/2
      Envelope DL 110 x 220mm
      Envelope C5 162 x 229 mm
      Envelope Monarch 3.875 x 7.5 in
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_OPTION_RESOLUTION
      300 X 300
      150 X 150
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_OPTION_COPIES
 1
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_OPTION_PAPER_TRAY
      USER DEFINED
      UPPER/ONLYONE
      ENVMANUAL
      MANUAL
      LOWER
END_PROPERTY
BEGIN_PROPERTY
      __AC_PRINTER_OPTION_COLLATE
 FALSE
END_PROPERTY


AcGetPrinterNames

Example   Member functions of AcGetPrinterNames

Represents a message to identify available printers.

Description

Creates a message for the administration server that requests the printers available to the client.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetPrinterNames	Returns names of available printers.


Example

AcGetPrinterNames getPrinterNames;

m_sendStatus =m_connection->SendRequest

(getPrinterNames, m_timeout);

RWOrdered printerNames=getPrinterNames.GetPrinterNames();

RWOrderedIterator l_iter((RWOrdered&) printerNames);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

}

printerNames.clearAndDestroy();


Member functions of AcGetPrinterNames

AcGetPrinterNames::GetPrinterNames


AcGetPrinterNames::GetPrinterNames

Accesses names of available printers.

Syntax

RWOrdered GetPrinterNames() const

Description

Returns a list of the printer names available to the client. The name of each element is the name of a printer and the string value of the element is a description of the printer. The first printer in the list is the system default printer.

When you are finished using the list of printer names returned by this function, delete it. In the previous example, the call to printerNames.clearAndDestroy() accomplished this deletion.


AcGetPrinterOptionDefaults

Example   See also   Member functions of AcGetPrinterOptionDefaults

Represents a message to get system default printer options.

Description

Creates a message for the administration server requesting the default values of the printer options at the system level. When an option property name has the same name as an attribute, you must specify the option through the system level defaults using the AcSetPrinterOptionDefaults message. The default value is the option having the same name as the attribute, which is returned by AcGetPrinterInformation::GetPrinterAttributes.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetPrinterName	Sets the name of the printer.
GetPrinterOptions	Returns default options in effect for the named printer.
GetDefaultPrinterFlag	Verifies that the named printer is the system default printer.


Example

AcGetPrinterOptionDefaults getPrinterOptionDefaults;

  AcProperty  modelProperty;

  AcProperty  locationProperty;

  AcProperty  descProperty;

  getPrinterOptionDefaults.SetPrinterName("\\HP LaserJet IIP");

  m_sendStatus =m_connection->SendRequest(  getPrinterOptionDefaults,

m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << "Default Flag " <<

  getPrinterOptionDefaults.GetDefaultPrinterFlag() << endl;

RWOrdered list =getPrinterOptionDefaults.GetPrinterOptions();

// code to print the list goes here; see egclient

list.clearAndDestroy();

  }


See also

AcGetPrinterInformation::GetPrinterAttributes


Member functions of AcGetPrinterOptionDefaults

AcGetPrinterOptionDefaults::SetPrinterName

AcGetPrinterOptionDefaults::GetPrinterOptions

AcGetPrinterOptionDefaults::GetDefaultPrinterFlag


AcGetPrinterOptionDefaults::SetPrinterName

Sets the name of the printer having default options to be retrieved by this object.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer, for example, "\\\\Lahaina\\HP LaserJet IIP", a network printer on machine Lahaina. The first backslash in a pair is the escape character.


AcGetPrinterOptionDefaults::GetPrinterOptions

Returns a list of values for default options that have been set for the specified printer.

Syntax

RWOrdered GetPrinterOptions() const

Description

This function returns an ordered collection of printer options. Delete the contents of the ordered collection when you are finished using it.


AcGetPrinterOptionDefaults::GetDefaultPrinterFlag

Returns TRUE if the printer is the default system printer.

Syntax

RWBoolean GetDefaultPrinterFlag() const

Description

This function compares the name of the default system printer to its member data, which names a printer. It returns TRUE if the names match; otherwise, it returns FALSE.


AcGetPrivilegesOfRole

Member functions of AcGetPrivilegesOfRole

Represents a message to access privileges for a role.

Description

Creates a message that queries the administration server for the privilege relationship between a role and an encyclopedia item. Once the server authenticates the request, it returns the role privileges from the access list of the encyclopedia item.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the role name to query for privileges.
SetObjectName	Uses the object's name to specify the encyclopedia item with the privilege relationship.
SetObjectID	Uses the object's identification to specify the encyclopedia item for the privilege relationship.
GetPrivilegeTypes	Gets a list of privilege types.
SetEffectivePrivilegesFlag	If TRUE, returns the privilege of the role based on the roles it belongs to, or if FALSE, returns the privileges explicitly set for the role.


Member functions of AcGetPrivilegesOfRole

AcGetPrivilegesOfRole::SetRoleName

AcGetPrivilegesOfRole::SetObjectName

AcGetPrivilegesOfRole::SetObjectID

AcGetPrivilegesOfRole::GetPrivilegeTypes


AcGetPrivilegesOfRole::SetRoleName

Sets the role name to query for privileges.

Syntax

void SetRoleName(const RWCollectableString& role_name)

role_name

The name of the role for the query, which must be a valid role on the administration server.


AcGetPrivilegesOfRole::SetObjectName

See also

Specifies the encyclopedia item with the privilege relationship, by name.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the object. This is the full name of the object, including the hierarchical path, filename, and file extension of the object. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path.

Description

This function uses the object's name for identification. AcGetPrivilegesOfRole::SetObjectID uses the object's ID, if available.


See also

AcGetPrivilegesOfRole::SetObjectID


AcGetPrivilegesOfRole::SetObjectID

See also

One of two ways to specify the encyclopedia item with the privilege relationship, by object ID.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the object. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.

Description

This function uses the object's ID for identification. AcGetPrivilegesOfRole::SetObjectName uses the object's name.


See also

AcGetPrivilegesOfRole::SetObjectName


AcGetPrivilegesOfRole::GetPrivilegeTypes

See also

Gets a list of privilege types.

Syntax

RWOrdered GetPrivilegeTypes() const

Description

This function returns an ordered list of privilege types. Call this function after sending a request to get privileges of a role.


See also

AcAddPrivilegeToUser::SetPrivilegeType


AcGetPrivilegesOfRole::SetEffectivePrivilegesFlag

Determines whether to return explicitly set privileges or those based on the role.

Syntax

void SetEffectivePrivilegesFlag (RWBoolean flag);

Description

If TRUE, returns the privilege of the role based on the roles it belongs to, or if FALSE, returns the privileges explicitly set for the role.


AcGetPrivilegesOfUser

Member functions of AcGetPrivilegesOfUser

Represents a message to access a user's privileges to report items or to Web Agent channels.

Description

Creates a message that queries the administration server for all privilege relationships between a user and an encyclopedia item. Once the server authenticates the request, it returns a list of privileges for the specified user.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
GetPrivilegeTypes	Gets a list of privilege types for the relationship between the specified user and encyclopedia object.
SetChannelName	Specifies the channel for the privilege query.
SetEffectivePrivilegesFlag	Returns the privilege of the user based on the roles that the user belongs to, or if set to FALSE, returns the privileges explicitly set for the user.
SetObjectID	Uses the object's identification to specify the encyclopedia item for the privilege query.
SetObjectName	Uses the object's name to specify the encyclopedia item for the privilege query.
SetUserName	Sets the user name to query for privilege relationships.


Member functions of AcGetPrivilegesOfUser

AcGetPrivilegesOfUser::GetPrivilegeTypes

AcGetPrivilegesOfUser::SetChannelName

AcGetPrivilegesOfUser::SetObjectID

AcGetPrivilegesOfUser::SetObjectName

AcGetPrivilegesOfUser::SetUserName


AcGetPrivilegesOfUser::GetPrivilegeTypes

Gets a list of privilege types for the relationship between the specified user and encyclopedia object.

Syntax

RWOrdered GetPrivilegeTypes() const

Description

Returns a list of privilege types for the relationship between the specified user and encyclopedia object. The list is empty if no privileges exist. Call this function after sending a request to get privileges of a user.


AcGetPrivilegesOfUser::SetChannelName

Establishes the name of the channel that the user has privileges on. The only channel privilege is read. Only an object or a channel, but not both, may be set in a specific privilege message.

Syntax

void SetChannelName(const RWCollectableString& channel_name)


AcGetPrivilegesOfUser::SetEffectivePrivilegesFlag

Determines whether to return explicitly set privileges or those based on the role.

Syntax

void SetEffectivePrivilegesFlag (RWBoolean flag);

Description

If TRUE, returns the privilege of the user based on the roles the user belongs to, or if FALSE, returns the privileges explicitly set for the user.


AcGetPrivilegesOfUser::SetObjectID

See also

Specifies the encyclopedia item for the privilege query.

Syntax

void SetObjectID(const RWCollectableString& object_id)

object_id

The unique server-assigned ID of the encyclopedia object. Only objects stored by persistent object servers have IDs; other objects can only be identified by their names or contents.

Description

This function uses the object's ID for identification. AcGetPrivilegesOfUser::SetObjectName uses the object's name.


See also

AcGetPrivilegesOfUser::SetObjectName


AcGetPrivilegesOfUser::SetObjectName

See also

One of two ways to specify the encyclopedia item for the privilege query.

Syntax

void SetObjectName(const RWCollectableString& object_name)

object_name

The user-defined name of the encyclopedia object. This is the full name of the object, including the hierarchical path, filename, and file extension of the object. Only objects stored by persistent object servers have hierarchical paths; other types of objects have names but no hierarchical path.

Description

This function uses the object's name for identification. AcGetPrivilegesOfUser::SetObjectID uses the object's ID, if available.


See also

AcGetPrivilegesOfUser::SetObjectID


AcGetPrivilegesOfUser::SetUserName

Sets the user name to query for privilege relationships.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The name of the user for the privilege query and a user in the access list of the encyclopedia item.


AcGetPrivilegeTypes

Member functions of AcGetPrivilegeTypes

Represents a message to access the various types of available privileges.

Description

Creates a message that queries the server for all privilege types. The server returns a list of all privileges, including the built-in types.

Constructor

This class has default and copy constructors only.

Public member function

Member function	Description
GetPrivilegeTypes	Gets a list of system privilege types.


Member functions of AcGetPrivilegeTypes

AcGetPrivilegeTypes::GetPrivilegeTypes


AcGetPrivilegeTypes::GetPrivilegeTypes

Gets a list of system privilege types.

Syntax

RWOrdered GetPrivilegeTypes() const

Description

This function returns an ordered list of system privileges. Call this function after sending a request to get privilege types.


AcGetRequestInformation

Example   Member functions of AcGetRequestInformation

Creates a message to get status information about a specified request.

Constructor

This class has default and copy constructors.

Description

With an AcGetRequestInformation object, client applications with the appropriate privilege can request and receive the status of a particular operation on an input or output object.

An input object is a parameter that is passed to the request. For example, an ROX input object is passed to a request to execute a report along with an ROV object for obtaining database usernames, passwords, and other execution options. An ROI input object is passed to a request to print a report.

An output object is a return value of the request. For example, a request to execute an ROX object returns the ID of the resulting ROI. The status information on the operation is sent to the request server while the operation is running. The request server stores the information in a repository accessible by this class.

Public member functions

Member function	Description
DeclareInterestInRequestID	Determines the request ID to use when querying this object for specific request information.
GetAllUsersRequestIDs	Retrieves the IDs of completed or pending requests.
GetBatchDisposition	Gets the batch disposition of the request.
GetEndDateAndTime	Returns the date and time that the request was last completed.
GetHostName	Returns the host name of the machine that will handle the request.
GetInputObjectID	Gets the ID of the input object.
GetInputObjectName	Gets the name of the input object.
GetName	Returns the name of the request.
GetOutputObjectName	Returns the object that is the result of the request.
GetParameterLists	Gets all of the parameter lists of the request.
GetPriority	Gets the scheduling precedence for running reports.
GetRequestID	Returns the ID of the first request found even if there are multiple requests that have request information.
GetRequestIDs	Returns the list of IDs that have request information.
GetSchedule	Gets the repeat schedule of this request.
GetSenderID	Returns the ID of the original sender of the request.
GetServerName	Returns the name of the server for the request.
GetServerNumber	Returns the number of the server handling the request if the request is currently executing.
GetServerType	Returns the type of server for the request.
GetStartDateandTime	Returns the last date and time the request was started.
GetStatusInformation	Gets the request's status information, a list of AcProperty objects.
IgnoreStatusInformation	Specifies whether or not the query should obtain request status information.
SetChannelName	Specifies the channel that wants information.
SetAllUsersCompleted RequestsFlag	Sets a flag to retrieve all completed requests for all users.
SetAllUsersPendingRequests Flag	Sets a flag to retrieve all pending requests for all users.
SetRequestID	Specifies the ID of the request with information about the status of an operation on an object.
SetRequestIDs	Specifies a list of IDs of requests with information on the status of a particular operation on an object.
SetRequestInstanceStartTime	Specifies the time of the specific request instance with the status of a particular operation on an object.
SetUserName	Specifies the user to give information to.


Example

This example shows how to access most of the information about request 123 using the member functions of this class. Assume that a server connection with the necessary privileges already exists.

RWCollectableString requestId = "123"

AcGetRequestInformation reqInfo;

reqInfo.SetRequestID(requestId);

m_sendStatus =m_connection->SendRequest(reqInfo, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << "RequestInfo for Id    : " << requestId << endl;

cout << "Name                  : " << reqInfo.GetName() << endl;

AcSenderID id = reqInfo.GetSenderID();

cout << "Sender Information    : " << endl;

cout << "    Name              : " << id.GetName() << endl;

cout << "    Host              : " << id.GetHostName() << endl;

cout << "    IP                : " << id.GetIPAddress() << endl;

cout << "    Date+Time         : " << id.GetDateAndTimeOfConnection()

  << endl;

cout << "Host Name Name        : " << reqInfo.GetHostName() << endl;

cout << "Server Type           : " << reqInfo.GetServerType() << endl;

cout << "Server Name           : " << reqInfo.GetServerName() << endl;

cout << "Server Number         : " << reqInfo.GetServerNumber() << endl;

cout << "Input Object ID       : " << reqInfo.GetInputObjectID() << endl;

cout << "Input Object Name     : " << reqInfo.GetInputObjectName() << endl;

cout << "Output  Object Name   : " << reqInfo.GetOutputObjectName()

<< endl;

}


Member functions of AcGetRequestInformation

AcGetRequestInformation:: DeclareInterestInRequestID

AcGetRequestInformation::GetAllUsersRequestIDs

AcGetRequestInformation::GetBatchDisposition

AcGetRequestInformation::GetEndDateAndTime

AcGetRequestInformation::GetHostName

AcGetRequestInformation::GetInputObjectID

AcGetRequestInformation::GetInputObjectName

AcGetRequestInformation::GetName

AcGetRequestInformation::GetOutputObjectName

AcGetRequestInformation::GetParameterLists

AcGetRequestInformation::GetPriority

AcGetRequestInformation::GetRequestID

AcGetRequestInformation::GetRequestIDs

AcGetRequestInformation::GetSchedule

AcGetRequestInformation::GetSenderID

AcGetRequestInformation::GetServerName

AcGetRequestInformation::GetServerNumber

AcGetRequestInformation::GetServerType

AcGetRequestInformation::GetStartDateAndTime

AcGetRequestInformation::GetStatusInformation

AcGetRequestInformation::IgnoreStatusInformation

AcGetRequestInformation::SetChannelName

AcGetRequestInformation:: SetAllUsersCompletedRequestsFlag

AcGetRequestInformation:: SetAllUsersPendingRequestsFlag

AcGetRequestInformation::SetRequestID

AcGetRequestInformation::SetRequestIDs

AcGetRequestInformation:: SetRequestInstanceStartTime

AcGetRequestInformation::SetUserName


AcGetRequestInformation:: DeclareInterestInRequestID

Sets the request ID to use when querying this object for specific request information.

Syntax

void DeclareInterestInRequestID(const RWCollectableString& request_id)

request_id

The identifier of the particular request of interest.

Description

If there is only one request ID being queried, this function does nothing. If a list of IDs are being queried, this function specifies the request ID to use for subsequent queries.


AcGetRequestInformation::GetAllUsersRequestIDs

Retrieves the IDs of completed or pending requests.

Syntax

RWOrdered GetAllUsersRequestIDs

Description

Returns the set of completed or pending request IDs that were flagged with SetAllUsersCompletedRequestsFlag and SetAllUsersPendingRequestsFlag, respectively. Call RWOrdered::closeAndDestroy to delete the list of request IDs when you are finished using it. Use this function after the Report Server has processed the set of requests. For each returned request ID, call DeclareInterestInRequestID to retrieve information about that particular request.


AcGetRequestInformation::GetBatchDisposition

Finds out whether a particular request is handled in batch mode.

Syntax

RWBoolean GetBatchDisposition() const

Description

This function ascertains whether or not a request is to be batched. A batch request is held by the request server until there is an operation server running that can handle the priority of the request. Batch requests are only useful for requests that have too low a priority for the servers running at the time the request was issued. Normally, if there is no server running that can handle the priority of a request (the request priority is too low), the request is failed, and the user that issued the request is notified of the failure.

Return value

TRUE specifies that this is a batch request. FALSE specifies that this is not a batch request.


AcGetRequestInformation::GetEndDateAndTime

Returns the date and time that the last request was completed, in UTC format.

Syntax

RWTime GetEndDateAndTime() const

Return value

Returns the date and time in UTC format, for example 04/23/97 13:18:15


AcGetRequestInformation::GetHostName

Returns the host name of the machine to handle the request.

Syntax

RWCollectableString GetHostName() const


AcGetRequestInformation::GetInputObjectID

Gets the ID of the input object.

Syntax

RWCollectableString GetInputObjectID() const

Description

Returns the ID of the request's input object. For example, the input object might be either an ROX item and execution is requested or an ROI item and printing is requested.

Retrieves the ID of the object only if it was set by the related Set calls, for example AcGetRequestInformation::SetRequestID, in the original request. For example, if the object name has been set on this request, the object ID cannot be obtained.


AcGetRequestInformation::GetInputObjectName

Gets the name of the input object.

Syntax

RWCollectableString GetInputObjectName() const

Description

This function retrieves the name of the object only if it was set by the related Set calls, for example AcGetRequestInformation::SetRequestName, in the original request. For example, if the object ID has been set on this request, the object name cannot be obtained. If the object name has been set on this request, the object ID cannot be obtained.


AcGetRequestInformation::GetName

Returns the name of the request.

Syntax

RWCollectableString GetName() const


AcGetRequestInformation::GetOutputObjectName

Returns the object that is the result of the request.

Syntax

RWCollectableString GetOutputObjectName() const

Description

The form of the returned object differs from one request to another, depending on the type of request and the form of the input object, and whether or not SetReturnObjectName was called on the original request. The name returned by the function includes updated versioning for the object.

Return value

This function either returns the name of the target object, such as the name of the ROI that results from execution of an ROX, or it returns an empty string if an ID was set instead of a name.


AcGetRequestInformation::GetParameterLists

Gets all of the parameter lists of the request.

Syntax

RWOrdered GetParameterLists() const

Description

This function returns lists of AcProperty objects, which contain input information, such as the ROV object names for an AcExecuteObject request.


AcGetRequestInformation::GetPriority

Gets the scheduling precedence for running a report.

Syntax

unsigned long GetPriority() const

Description

This function accesses scheduling information for the report that is specified by SetRequestID or DeclareInterestInRequestID. The function returns an integer 0-1000, the limit imposed by the Navigator's Requester dialog box, which sets high, medium, or low priority.


AcGetRequestInformation::GetRequestID

Returns the ID of the first request found even if there are multiple requests that have request information.

Syntax

RWCollectableString GetRequestID() const

Description

This function provides backward compatibility with applications written before multiple requests were handled.


AcGetRequestInformation::GetRequestIDs

Returns the list of IDs for this request information.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns a list of request IDs as an RWOrdered collection. Call RWOrdered::closeAndDestroy to delete the collection when you are finished using it.


AcGetRequestInformation::GetSchedule

Gets the repeat schedule of the request specified by this object.

Syntax

RWOrdered GetSchedule() const

Description

This function returns a list of AcSchedule objects that specify the schedule of this request. Call RWOrdered::closeAndDestroy to delete the list when you are finished using it.


AcGetRequestInformation::GetSenderID

Returns the ID of the original sender of the request.

Syntax

AcSenderID GetSenderID() const


AcGetRequestInformation::GetServerName

Returns the name of the server for the request.

Syntax

RWCollectableString GetServerName() const


AcGetRequestInformation::GetServerNumber

Returns the number of the server handling the request if the request is currently executing.

Syntax

RWCollectableString GetServerNumber() const

Description

There can be multiple instances of the request server running on one host. This function returns the server number handling the request.


AcGetRequestInformation::GetServerType

Returns the type of server for the request.

Syntax

RWCollectableString GetServerType() const

Description

The file util/srvtypes.h defines the following server types that this function returns:

"__AC_CONNECTION_SERVER"

"__AC_REQUEST_SERVER"

"__AC_ADMINISTRATION_SERVER"

"__AC_PERSISTENT_OBJECT_SERVER"

"__AC_FACTORY_SERVER"

"__AC_PRINT_SERVER"

"__AC_REQUEST_SERVER"


AcGetRequestInformation::GetStartDateAndTime

Returns the last date and time that the request was started.

Syntax

RWTime GetStartDateAndTime() const


AcGetRequestInformation::GetStatusInformation

Gets request status information, a list of AcProperty objects, for the request specified by this object.

Syntax

RwOrdered GetStatusInformation() const

Description

This function returns a list of AcProperty objects that each contain a property list. The first property in each list contains an unsigned integer value representing the date and time of the status information in UTC format, for example 04/23/97 13:18:15.

The second property in each list contains a string value with status information for that date and time. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.


AcGetRequestInformation::IgnoreStatusInformation

Specifies whether or not the query should obtain request status information.

Syntax

void IgnoreStatusInformation(RWBoolean flag)

flag

To ignore status information, set this parameter to TRUE. The default is FALSE.


AcGetRequestInformation::SetChannelName

Specifies the channel that wants information. Important: Do not set the user name, but do set the channel name to get channel information.

Syntax

void SetChannelName(const RWCollectableString& channel_name);

channel_name

The name of the channel that wants information.


AcGetRequestInformation:: SetAllUsersCompletedRequestsFlag

Sets a flag to retrieve all completed requests for all users.

Syntax

void SetAllUsersCompletedRequestsFlag(RWBoolean flag)

Description

The flag set by this function is reset when you call one of the following member functions:

•	SetUserName

•	SetRequestID

•	SetRequestIDs

•	SetRequestInstanceStartTime

•	IgnoreStatusInformation


AcGetRequestInformation:: SetAllUsersPendingRequestsFlag

Sets a flag to retrieve all pending requests for all users.

Syntax

void SetAllUsersPendingRequestsFlag(RWBoolean flag)

Description

The flag set by this function is reset when you call one of the following member functions:

•	SetUserName

•	SetRequestID

•	SetRequestIDs

•	SetRequestInstanceStartTime

•	IgnoreStatusInformation


AcGetRequestInformation::SetRequestID

Specifies the ID of a request to query for status information about the operation on an object. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetRequestID(const RWCollectableString& request_id)

request_id

The identifier for the request.


AcGetRequestInformation::SetRequestIDs

Specifies a list of identifiers of requests to query for status information about the operation on an object. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetRequestIDs(const RWOrdered& request_id_list)

request_id_list

The list of request identifiers.


AcGetRequestInformation:: SetRequestInstanceStartTime

Specifies the time of the specific request instance to query for status information. For more information on the status properties, see Request status informationand msgpname.h in the util directory of the Report Server API.

Syntax

void SetRequestInstanceStartTime(const RWCollectableTime& start_time)

start_time

The start time of the request instance.


AcGetRequestInformation::SetUserName

Specifies the user requesting information. Do not set the user name if what you want is channel information.

Syntax

void SetUserName(const RWCollectableString& user_name);

user_name

The name of the user who wants information.


AcGetRoleNames

Example   Member functions of AcGetRoleNames

Represents a message to access available role names.

Description

Creates a message that queries the server for all role names. The server returns a list of all roles, including the built-in administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
GetRoleNames	Gets all role names from the administration server.


Example

The following example shows how to retrieve all role names from the server. This procedure assumes that a server connection called m_connection exists.

RWOrdered roleList;

int m_timeout=100000000;

AcGetRoleNames getRoles;

m_sendStatus =m_connection->SendRequest(getRoles, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  roleList = getRoles.GetRoleNames();

  }


Member functions of AcGetRoleNames

AcGetRoleNames::GetRoleNames


AcGetRoleNames::GetRoleNames

Gets all role names from the administration server.

Syntax

RWOrdered GetRoleNames() const

Description

This function returns an ordered list of role names. Call this function after sending a request to get role names.


AcGetRoleOwner

Member functions of AcGetRoleOwner

Represents a message to find the owner of a role.

Description

Creates a message that queries the administration server for the owner of a specific role. Since the owner generally has full administration privileges for the role, it is sometimes necessary to discover the owner before implementing role changes.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the name of the role to query for an owner.
GetUserName	Gets the user name of the role owner.


Member functions of AcGetRoleOwner

AcGetRoleOwner::SetRoleName

AcGetRoleOwner::GetUserName


AcGetRoleOwner::SetRoleName

Sets the name of the role to query for an owner.

Syntax

void SetRoleName(const RWCollectableString& name)

name

A valid role name on the administration server.


AcGetRoleOwner::GetUserName

Gets the user name of the role owner.

Syntax

RWCollectableString GetUserName() const

Description

This function returns the user name of the role owner. Send a request to get role owner before calling this function.


AcGetRolesOfRole

Member functions of AcGetRolesOfRole

Represents a message to identify inherited roles of a certain role.

Description

Creates a message that queries the administration server for the roles inherited by the specified role. Use this function to determine the inheritance tree for a hierarchical role relationship, working down one hierarchal level at a time.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the role name to query for inherited roles.
GetRoleNames	Gets a list of roles inherited by the specified role.


Member functions of AcGetRolesOfRole

AcGetRolesOfRole::SetRoleName

AcGetRolesOfRole::GetRoleNames


AcGetRolesOfRole::SetRoleName

Sets the role name to query for inherited roles.

Syntax

void SetRoleName(const RWCollectableString& name)

name

A valid role name on the administration server.


AcGetRolesOfRole::GetRoleNames

Gets a list of role names inherited by the specified role.

Syntax

RWOrdered GetRoleNames() const

Description

This function returns an ordered list of inherited role names. Call this function after sending a request to get the roles of a role.


AcGetRolesOfUser

Example   Member functions of AcGetRolesOfUser

Represents a message to access the roles of a certain user.

Description

Creates a message that queries the server for the roles of a specific user. Client applications use this and other role classes to manage role membership. The client application can perform this query from any connection to the server.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user for the role query.
GetRoleNames	Gets a list of role names for the specified user.


Example

This example shows how to print user names and roles.

AcGetUserNames getUsers;

m_sendStatus =m_connection->SendRequest(getUsers, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered userList = getUsers.GetUserNames();

RWOrderedIterator iter(userList);

RWCollectableString * entry;

while(entry = (RWCollectableString*)iter()){

RWCollectableString printString;

cout << "User Name     :" << *entry << endl;

//get roles

cout << "Roles         :";

AcGetRolesOfUser getRolesOfUser;

getRolesOfUser.SetUserName(*entry);

m_sendStatus =m_connection->SendRequest

(getRolesOfUser, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered roles = getRolesOfUser.GetRoleNames();

RWOrderedIterator l_iter((RWOrdered&) roles);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(),

RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << *l_string << endl;

} //while

roles.clearAndDestroy();

} // if

}	//while

} //if


Member functions of AcGetRolesOfUser

AcGetRolesOfUser::SetUserName

AcGetRolesOfUser::GetRoleNames


AcGetRolesOfUser::SetUserName

Sets the name of the user for the role query.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcGetRolesOfUser::GetRoleNames

Gets a list of role names for the specified user.

Syntax

RWOrdered GetRoleNames() const

Description

This function returns a list of role names for the specified user. The list is empty if the user has no assigned roles. Send the request to get the roles of the user before calling this function.


AcGetRolesWithRole

Member functions of AcGetRolesWithRole

Represents a message to find the base role of a derived role.

Description

Creates a message for the administration server that queries for the base role of an inherited role. Use this function to determine the inheritance tree, working up one level of the hierarchy at a time.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the base role name to query for derived roles.
GetRoleNames	Gets a list of role names that inherit the specified role.


Member functions of AcGetRolesWithRole

AcGetRolesWithRole::SetRoleName

AcGetRolesWithRole::GetRoleNames


AcGetRolesWithRole::SetRoleName

Sets the base role name to query for derived roles.

Syntax

void SetRoleName(const RWCollectableString& name)

name

A valid role name on the administration server.


AcGetRolesWithRole::GetRoleNames

Gets a list of role names that inherit the specified base role.

Syntax

RWOrdered GetRoleNames() const

Description

This function returns an ordered list of derived role names. Call this function after sending a request to get the roles with a role.


AcGetServerTime

Example   Member functions of AcGetServerTime

Creates a message to read the time on the server machine.

Description

This class represents a message to the request server to get the time in UTC format from the server machine.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetServerTime	Returns the server time.


Example

This example assumes you have a connection to send an AcGetServerTime message object from the SendRequest function, requesting the server time. An RWCollectable object is created to represent the formatted time, which is returned from a member function AcGetServerTime::GetServerTime.

AcGetServerTime serverTimeInfo; m_sendStatus =m_connection
->SendRequest(serverTimeInfo,m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWCollectableTime serverTime;

serverTime= serverTimeInfo.GetServerTime();

}


Member functions of AcGetServerTime

AcGetServerTime::GetServerTime


AcGetServerTime::GetServerTime

Returns the server time.

Syntax

RWCollectableTime GetServerTime() const


AcGetUniqueRequestID

See also   Member functions of AcGetUniqueRequestID

Represents a request that is sent using a message class to get an identifier that is unique to the connected server.

Constructor

This class has default and copy constructors.

Description

Use this function to get a unique request ID when you want to specify the request identifier to the server. Call AcRequest::SetForcedRequestID after calling this function to set the ID to the given unique value. If you do not specify an ID, the system generates one.

Public member functions

Member function	Description
GetRequestID	Returns the identifier that is unique to the connected server.


See also

AcRequest::SetForcedRequestID


Member functions of AcGetUniqueRequestID

AcGetUniqueRequestID::GetRequestID


AcGetUniqueRequestID::GetRequestID

Returns the identifier that is unique to the connected server.

Syntax

RWCollectableString GetRequestID() const


AcGetUserCompletedRequests

Example   Member functions of AcGetUserCompletedRequests

Creates a message to get the IDs of the completed requests for a specified user.

Description

AcGetUserCompletedRequests encapsulates functions to retrieve completed requests in the Request Completed folder for a certain user. If the user name is not set using the member function SetUserName, the completed requests for the Administrator are retrieved.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetRequestIDs	Returns the request IDs based on settings such as the filter that designates which requests the caller wants.
GetRequestName	Gets the names of the requests that the caller is interested in.
GetRequestNameFilter	Specifies the names of the requests that the caller is interested in.
SetUserName	Specifies the user name to query for contents of the user's Request Completed folder in the Report Encyclopedia.


Example

This example gets all the completed requests for John Doe.

AcGetUserCompletedRequests compReqs;

compReqs.SetUserName("John Doe");

m_sendStatus =m_connection->SendRequest(compReqs, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered compIds = compReqs.GetRequestIDs();

cout << "Completed Requests for user : " <<

(char*)userName.data()<< endl;

// code to print the list, complds, goes here

}


Member functions of AcGetUserCompletedRequests

AcGetUserCompletedRequests::GetRequestIDs

AcGetUserCompletedRequests::GetRequestName

AcGetUserCompletedRequests:: SetRequestNameFilter

AcGetUserCompletedRequests::SetUserName


AcGetUserCompletedRequests::GetRequestIDs

Returns the request IDs based on settings, such as the filter that designates which requests the caller wants.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns the request IDs as an ordered polymorphic collection of objects. Delete the contents of the collection when you are finished using it. Call this function after calling SetRequestNameFilter to get specific IDs.


AcGetUserCompletedRequests::GetRequestName

Gets the names of the requests that the caller is interested in.

Syntax

RWOrdered GetRequestNameFilter() const

Description

This function returns an ordered list of request names. Delete the contents of the list when you are finished using it.


AcGetUserCompletedRequests:: SetRequestNameFilter

Specifies the names of the requests that the caller is interested in.

Syntax

void SetRequestNameFilter(const RWOrdered& request_names)

request_names

The names of the requests are of type RWOrdered, an ordered polymorphic collection of objects.


AcGetUserCompletedRequests::SetUserName

Specifies the user name to query for contents of the user's Request Completed folder in the Report Encyclopedia.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The user name.


AcGetUserData

Member functions of AcGetUserData

Represents a request to get data on a specified user.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetUserData	Returns the name, preferences, and role names of a named user or all users.
SetUserName	Specifies the user name to query for data.


Member functions of AcGetUserData

AcGetUserData::GetUserData

AcGetUserData::SetUserName


AcGetUserData::GetUserData

Returns name, preferences, and role names of the user. If you did not set a user name, the server returns data for all users.

Syntax

RWOrdered GetUserData() const;


AcGetUserData::SetUserName

Sets the name of the user for the data query. If you did not set a name, the server returns data on all users.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcGetUserDefaultPrinterName

Member functions of AcGetUserDefaultPrinterName

Creates a message requesting the name of the default printer for a certain user.

Description

By default the user name of the sender is used.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetUserName	Sets the name of the user of the default printer to be identified using this message.
GetPrinterName	Returns the name of the default printer for a certain user or, if none is specified, for the sender of the request.


Member functions of AcGetUserDefaultPrinterName

AcGetUserDefaultPrinterName::SetUserName

AcGetUserDefaultPrinterName::GetPrinterName


AcGetUserDefaultPrinterName::SetUserName

Sets the name of the user of the default printer to be identified using this message.

Syntax

void SetUserName(const RWCollectableString& name)

Description

This derived function sets the name of the user whose default printer name you want to find. By default the user name of the sender is used. The sender is the user name passed to AcClientConnection to make the connection for this transaction.


AcGetUserDefaultPrinterName::GetPrinterName

Returns the name of the default printer for a certain user or, if none is specified, for the sender of the request.

Syntax

RWCollectableString SetPrinterName() const


AcGetUserNames

Example   Member functions of AcGetUserNames

Represents a message to access all user names.

Description

Creates a message that queries the administration server for the names of all the users. The server returns a list of user names.

Constructor

This class has default and copy constructors only.


Example

The following example shows how to get a complete list of user names from the administration server. This code assumes a server connection called m_connection already exists.

RWOrdered userList;

int m_timeout=100000000;

AcGetUserNames getUsersMsg;

m_sendStatus =m_connection->SendRequest(getUsersMsg, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

  userList = getUsersMsg.GetUserNames(); }

Public member function

Member function	Description
GetUserNames	Gets the names of all users.


Member functions of AcGetUserNames

AcGetUserNames::GetUserNames


AcGetUserNames::GetUserNames

Gets the names of all users from the administration server.

Syntax

RWOrdered GetUserNames() const

Description

This function returns the names of all users as an ordered list. Call this function after sending a request to get user names.


AcGetUserPendingRequests

Example   Member functions of AcGetUserPendingRequests

Represents a request to identify a user's pending requests.

Description

Creates a message to get the IDs of outstanding pending requests for a specified user. The request server places scheduled requests on the priority queues. Requests run when it is time to run them and in the order in which they are placed on the queue. A request is pending if it is in the queue awaiting execution. AcGetUserPendingRequests can retrieve the number of pending requests made by a particular user. If the user name is not set with the member function SetUserName, the pending requests for the Administrator are retrieved.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetRequestIDs	Returns the request IDs of outstanding pending requests.
GetRequestNameFilter	Gets the names of the requests that the caller is interested in.
SetRequestNameFilter	Specifies the names of the requests that the caller is interested in.
SetUserName	Specifies the user name to query for pending requests.


Example

This example gets all the pending requests for John Doe.

int m_timeout=100000000;

AcGetUserPendingRequests pendReqs;

pendReqs.SetUserName("John Doe");

m_sendStatus =m_connection->SendRequest(pendReqs, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered pendIds = pendReqs.GetRequestIDs();

cout << "Active Requests for user : " <<(char*)userName.data() << endl;

RWOrderedIterator l_iter((RWOrdered&) pendIds);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

}

pendIds.clearAndDestroy();

}


Member functions of AcGetUserPendingRequests

AcGetUserPendingRequests::GetRequestIDs

AcGetUserPendingRequests:: GetRequestNameFilter

AcGetUserPendingRequests:: SetRequestNameFilter

AcGetUserPendingRequests::SetUserName


AcGetUserPendingRequests::GetRequestIDs

Returns the request IDs.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns an ordered list of request IDs. Delete the contents of the list when you are finished using it.


AcGetUserPendingRequests:: GetRequestNameFilter

Gets the names of the requests that the caller is interested in.

Syntax

RWOrdered GetRequestNameFilter() const

Description

This function returns the list of request names, an ordered polymorphic collection of objects. Delete the contents of the list when you are finished using it.


AcGetUserPendingRequests:: SetRequestNameFilter

Specifies the names of the requests that the caller is interested in.

Syntax

void SetRequestNameFilter(const RWOrdered& request_names)

request_names

The names of the requests are of type RWOrdered, an ordered polymorphic collection of objects.


AcGetUserPendingRequests::SetUserName

Specifies the user name to query for pending requests.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The user name.


AcGetUserPreferences

Example   See also   Member functions of AcGetUserPreferences

Represents a message to access user preferences.

Description

Creates a message that gets all of the preferences for a certain user from the administration server.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the user name to query for preferences.
GetPreferences	Gets the user's preferences from the message object.


Example

The following example shows how to retrieve the administrator's preferences.

AcGetUserPreferences getUserPreferences;int m_timeout=100000000;

getUserPreferences.SetUserName("Administrator");

m_sendStatus =m_connection->SendRequest(getUserPreferences, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered preferences = getUserPreferences.GetUserPreferences();

RWOrderedIterator l_iter((RWOrdered&) preferences);

AcProperty* property;

while (property = RW_SAFE_CAST(l_iter(), AcProperty, __ACPROPERTY)) {

cout <<  property->GetName() << ". . . . . . . . ."

<< property->GetStringValue() << endl;

}

preferences.clearAndDestroy();

}

The output from this example might look like this:

Connected To Server With  Status  : 0
__AC_USER_EMAIL_ID. . . . . . . . .
__AC_USER_EMAIL_FORM. . . . . . . . .
__AC_USER_HOME_FOLDER. . . . . . . . .
__AC_USER_NOTIFICATION_TYPE. . . . . . . . .
__AC_USER_SERVER_NOTICE. . . . . . . . .Yes
__AC_USER_FIRST_VISIBLE_FOLDER. . . . . . . . .1
__AC_USER_SELECTED_ITEMS. . . . . . . . .
__AC_USER_EXPANDED_FOLDERS. . . . . . . . .
__AC_USER_MAX_PRIORITY. . . . . . . . .
__AC_USER_DEFAULT_OBJECT_PRIVILEGES. . . . . . . . .
__AC_USER_MAX_COMPLETED. . . . . . . . .20


See also

AcProperty


Member functions of AcGetUserPreferences

AcGetUserPreferences::SetUserName

AcGetUserPreferences::GetPreferences


AcGetUserPreferences::SetUserName

Sets the user name to query for preferences.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcGetUserPreferences::GetPreferences

Gets the user's preferences from the message object.

Syntax

RWOrdered GetPreferences() const

Description

This function returns the user's preferences as a list of AcProperty objects. Preferences include both system-defined and user-defined properties. Call this function after sending the request to get the user preferences. The following table lists the system properties.

Property	Description
__AC_USER_EMAIL_ID	E-mail address for e-mail completion notification.
__AC_USER_HOME_FOLDER	User's home folder.
__AC_USER_NOTIFICATION_ TYPE	Type of completion notification - 'e-mail' or 'server'.
__AC_USER_DEFAULT_ OBJECT_PRIVILEGES	Specifies privileges to be set at the time of creation on any object created by the user. The value of the property is a property list. The name of each property in the list is a role ID or user ID, depending on the semantic type of the property. The semantic type of the property must be either AC_SEMANTIC_TYPE_ROLE or AC_SEMANTIC_TYPE_USER  The value of each property in the list is a string list containing all of the privilege types to be added to the role or user.
__AC_USER_MAX_PRIORITY	Only used by the administrator to specify maximum priorities for each user. The value of the property is a property list. The name of each property in the list is a user ID. The value of the property is an unsigned integer that specifies the user's maximum priority. AC_USER_MAX_PRIORITY does not contain a value for a user if the value differs from the default, 500. Do not explicitly set this property to the default, because doing so slows operations, but the condition does not persist over reboots.
__AC_USER_MAX_COMPLETED	The number of completed requests displayed in the Completed Folder at one time.
__AC_USER_FIRST_VISIBLE_ FOLDER	Object ID of first visible folder from the end of the last user login. This is the topmost folder visible due to the scroll position.
__AC_USER_SELECTED_ ITEMS	String list of object IDs that were selected at the end of the last user login.
__AC_USER_EXPANDED_ FOLDERS	String list of object IDs of folders that were expanded at the end of the last user login.
__AC_USER_SERVER_NOTICE	The message that is sent to a group when the server shuts down.


AcGetUserPrinterOptionDefaults

Member functions of AcGetUserPrinterOptionDefaults

Represents a message to get the user-level default options for the printer.

Constructor

This class has default and copy constructors.

Description

Creates a message requesting the default printer options at the user level. Also encapsulates functionality for determining if a named printer is the user's default printer.

Public member functions

Member function	Description
GetDefaultPrinterFlag	Identifies the default printer for the user.
GetPrinterOptionDefaults	Returns a list of the default option values that have been set for the specified printer.
SetPrinterName	Identifies which of the user's printers have default options to be accessed.
SetUserName	Sets the user name to query for the default printer options.


Member functions of AcGetUserPrinterOptionDefaults

AcGetUserPrinterOptionDefaults:: GetDefaultPrinterFlag

AcGetUserPrinterOptionDefaults:: GetPrinterOptionDefaults

AcGetUserPrinterOptionDefaults::SetPrinterName

AcGetUserPrinterOptionDefaults::SetUserName


AcGetUserPrinterOptionDefaults:: GetDefaultPrinterFlag

Returns TRUE if the specified printer is the default printer for the user; otherwise, it returns FALSE.

Syntax

RWBoolean GetDefaultPrinterFlag() const


AcGetUserPrinterOptionDefaults:: GetPrinterOptionDefaults

Returns a list of the default option values that have been set for the specified printer.

Syntax

RWOrdered GetPrinterOptionDefaults() const

Description

This function returns a list of default options for a printer. Delete the contents of the list when you are finished using it.


AcGetUserPrinterOptionDefaults::SetPrinterName

Identifies which of the user's printers have default options to access.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer, for example, "\\\\Lahaina\\HP

 LaserJet IIP", a network printer on machine Lahaina.


AcGetUserPrinterOptionDefaults::SetUserName

Sets the name of the user whose default printer options are sought.

Syntax

void SetUserName(const RWCollectableString& name)

Description

Names the user whose default printer options are accessed. By default the user name of the sender is used. The sender is the user named at connection time in AcClientConnection.


AcGetUserScheduleRequests

Example   Member functions of AcGetUserScheduleRequests

Creates a message to get the IDs of the schedule requests for the specified user.

Description

This class represents a request for getting the schedule requests for a user. Schedules are stored in a repository that the request server reads at start-up. When it is time to execute a scheduled request, it is placed on the priority queues and run in turn. The schedule requests managed by this class are requests made with operation servers by the request server when it is connected to a user object with a request.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetAllUsersScheduleRequests Flag	Sets a flag to get the request IDs of all users, not the request IDs of a named user.
SetUserName	Specifies the user name to query for schedule requests.
GetRequestIDs	Returns the IDs of the requests scheduled for a particular user.
SetRequestNameFilter	Specifies the names of the requests that the caller is interested in.
GetRequestNameFilter	Gets the names of the requests that the caller is interested in.


Example

This example gets the IDs of schedule requests for William. The request IDs are returned in the RWOrdered structure, so call clearAndDestroy when the structure is no longer needed.

RWCollectableString m_userName="William";

int m_timeout=100000000;

m_password="";RWCollectableString requestId;

AcGetUserScheduleRequests schedReqs;

schedReqs.SetUserName(m_userName);

m_sendStatus =m_connection->SendRequest(schedReqs, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

}

RWOrdered schedIds = schedReqs.GetRequestIDs();

cout << "Scheduled Requests for User :"<<(char*)m_userName.data()
<< endl;

RWOrderedIterator l_iter((RWOrdered&) schedIds);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

requestId = *l_string;

}


Member functions of AcGetUserScheduleRequests

AcGetUserScheduleRequests::SetUserName

AcGetUserScheduleRequests::GetRequestIDs

AcGetUserScheduleRequests:: SetRequestNameFilter

AcGetUserScheduleRequests:: GetRequestNameFilter


AcGetUserScheduleRequests:: SetAllUsersScheduleRequestsFlag

Sets a flag to get the request IDs of all users, not the request IDs of a named user.

Syntax

void SetAllUsersScheduleRequestsFlag(RWBoolean flag)

flag

If TRUE, calling GetRequestIDs returns the set of scheduled requests for all users. If FALSE and if you set a user name by calling SetUserName, calling GetRequestIDs returns the set of scheduled requests for the named use. If FALSE and if you did not set a user name, calling GetRequestIDs returns the scheduled requests for the Administrator.


AcGetUserScheduleRequests::SetUserName

Specifies the user name to query for schedule requests. If no name is set, the server queries the Administrator name.

Syntax

void SetUserName(const RWCollectableString& user_name)

user_name

The user name.


AcGetUserScheduleRequests::GetRequestIDs

Returns the IDs of the requests scheduled for a particular user.

Syntax

RWOrdered GetRequestIDs() const

Description

This function returns the IDs as an ordered, polymorphic collection of objects. Delete the contents of the collection when you are finished using it.


AcGetUserScheduleRequests:: SetRequestNameFilter

Specifies the names of the requests that the caller is interested in.

Syntax

void SetRequestNameFilter(const RWOrdered& request_names)

request_names

The names of the requests of type RWOrdered, a polymorphic collection of objects.


AcGetUserScheduleRequests:: GetRequestNameFilter

Gets the names of the requests that the caller is interested in.

Syntax

RWOrdered GetRequestNameFilter() const

Description

This function returns the request names as an ordered, polymorphic collection of objects. Delete the contents of the collection when you are finished using it.


AcGetUsersWithRole

Member functions of AcGetUsersWithRole

Represents a message to identify users with a certain role.

Description

Creates a message that queries the administration server for the users with a particular role. Client applications use this and other role classes to manage role membership. The client application can perform this query from any connection to the server.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRoleName	Sets the name of the role to query for users.
GetUserNames	Gets a list of user names associated with the specified role.


Member functions of AcGetUsersWithRole

AcGetUsersWithRole::SetRoleName

AcGetUsersWithRole::GetUserNames


AcGetUsersWithRole::SetRoleName

Sets the name of the role to query for users.

Syntax

void SetRoleName(const RWCollectableString& name)

name

The name of the role to query, which must be a valid role on the administration server.


AcGetUsersWithRole::GetUserNames

Gets a list of user names associated with the specified role.

Syntax

RWOrdered GetUserNames() const

Description

This function returns a list of user names associated with the specified role. The list is empty if no users are assigned to the role. Call this function after sending a request to get users with role.


AcMessage

See also   Member functions of AcMessage

A base class for deriving message objects to be sent from process to process.

Description

AcMessage objects represent a message between two or more processes. The contents of message objects are reference counted and only freed when there are no more references to the contents. Once a message has been sent by a client, it cannot be resent. The client must make a copy of the message's contents, using CopyContents(), and send the copy. This prevents messages with duplicate IDs.

Constructor

This class has default and copy constructors.

Destructor

There are no side effects when an AcMessage object is destroyed. If the message has been sent, and is waiting for a response, the contents are not destroyed, because the AcClientConnection object has a reference to the contents.

Public member functions

Member function	Description
IsNull	Determines whether a message has properties or not.
CopyContents	Loads the contents of a message into this message object.
GetType	Determines the type (notice, request, or none) of the message.
GetID	Retrieves the message ID.
GetName	Retrieves the message name.
Protected member functions

Member function	Description
SetName	Sets the name of the message.
AddProperty	Adds a property value to the end of the named property list.
GetPropertyListNames	Gets the names of the property lists in this message.
GetCopyOfPropertyListNames	Retrieves a copy of the names of the property lists in this message.
GetPropertyList	Retrieves the values of the named property list.
GetCopyOfPropertyList	Retrieves a copy of the values of the named property list.


See also

AcExecuteAndPrintObject


Member functions of AcMessage

AcMessage::IsNull

AcMessage::CopyContents

AcMessage::GetType

AcMessage::GetID

AcMessage::GetName

AcMessage::SetName

AcMessage::AddProperty

AcMessage::GetPropertyListNames

AcMessage::GetCopyOfPropertyListNames

AcMessage::GetPropertyList

AcMessage::GetCopyOfPropertyList


AcMessage::IsNull

Determines whether a message has properties or not.

Syntax

RWBoolean IsNull() const

Description

Returns TRUE if this is a NULL message. Returns FALSE if the message has any properties. If the message contains a name, type, and ID only, it is considered to be a NULL message.


AcMessage::CopyContents

Loads contents of a message into this message object.

Syntax

void CopyContents(const AcMessage& message) const

Description

This function copies the contents of the given message into this message object. This object retains its original ID, name, and type. The object's name and type are copied only if they aren't already set. The properties of the specified message are always copied.


AcMessage::GetType

Determines the type of the message (notice, request, or none).

Syntax

virtual AcMessage::AcMessageType GetType() const

Description

Returns the type of message. AcMessageType is a nested enum that defines the message types. The following types are defined:

•	AcMessage::AC_NO_TYPE

•	AcMessage::AC_NOTICE

•	AcMessage::AC_REQUEST


AcMessage::GetID

Retrieves the message ID.

Syntax

RWCollectableString GetID() const

Description

Gets the unique ID of the message. Every message has a unique ID that can be traced through every send and forward of the message. The ID of a specific message object never changes.


AcMessage::GetName

Retrieves the message name.

Syntax

RWCollectableString GetName() const

Description

Returns the name of the message.


AcMessage::SetName

Sets the name of the message. Protected.

Syntax

void SetName(const RWCollectableString& name)


AcMessage::AddProperty

Appends a property value to the end of the named property list. Protected.

Syntax

void AddProperty(const RWCollectableString &list_name, const AcProperty& value)

list_name

The name of the property list to add to.

value

The value to add. The value is copied by the message. If the value is modified after being added to the message, the message is not affected.

Description

All of the data and attributes of different types of messages (requests, notices, and so on) are stored as properties.


AcMessage::GetPropertyListNames

Retrieves the names of the property lists in this message. Protected.

Syntax

RWSet& GetPropertyListNames()

Description

Gets the names of the property lists in this message. If the returned set is a reference to the set the message owns, the message is modified when the set is modified (names are added, deleted, or modified). Delete the contents of the set when you no longer need it.


AcMessage::GetCopyOfPropertyListNames

Retrieves a copy of the names of the property lists in this message. Protected.

Syntax

RWSet GetCopyOfPropertyListNames() const

Description

Gets the names of the property lists in this message. Modifications to the list of names added, deleted, or modified do not modify the message. Delete the contents of the set returned by this function.


AcMessage::GetPropertyList

Retrieves the values of the named property list. Protected.

Syntax

RWOrdered& GetPropertyListconst RWCollectableString& list_name)

list_name

The name of the property list.

Description

Gets the names of the property lists in this message. If the returned set is a reference to the set the message owns, the message is modified when the set is modified (names are added, deleted, or modified). Delete the contents of the set when you no longer need it.


AcMessage::GetCopyOfPropertyList

Returns a copy of the values of the named property list. Protected.

Syntax

RWOrdered  GetCopyOfPropertyList(const RWCollectableString& list_name) const

list_name

The name of the property list.

Description

Retrieves a copy of the values of the named property list. You can modify the copy without affecting the message. Modifications include adding, deleting, or changing values. When you no longer need the copy of the property list, delete its contents.


AcMessageSendError

Example   Member functions of AcMessageSendError

Encapsulates detailed information about errors that occur when messages are sent.

Description

AcMessageSendError objects provide detailed information about errors that occur when messages are sent. For example, a successful send operation may encounter a condition that results in a warning message to the sender. Such a warning condition occurs when an object ID targeted by a request is a forward reference. This class can also provide specific reasons for a message send failure, such as the object targeted by the request does not exist. For more information, see Interpreting Report Server errors.

Constructor

This class has copy and default constructors.

Public member functions

Member function	Description
GetErrorSeverity	Indicates the seriousness of the error.
GetErrorName	Retrieves the name of the error that may indicate the cause.
GetErrorListName	Retrieves the name of the list of messages related to the error.
GetErrorLocation	Returns the name of the server procedure related to the error or the location of the error, such as the machine name.
GetErrorDescription	Retrieves some information about the error.


Example

This example displays the following output:

C:\Actuate\Server\rsapi\NT\examples>egclientD
MESSAGE REPLY ERROR
Severity    : NOT_RETRYABLE
Name        : AC_SEND_ERROR_NO_CONNECTION
Location    : haleakala
Description : Not connected to the server

This example initializes AcClientConnection with an invalid machine name, wrongname, and attempts to send a message to get the names of users. The example creates an AcMessageSendError object, error, to receive the error message. It then calls the AcClientConnection function GetMessageSendError to access the message. The global function AcErrorSeverityToString converts the enumerated type of error to a string, which is sent to standard output along with the AcMessageSendError values for the error name, the machine on which the error occurred, and a description of the error.

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcClientConnection  *m_connection;

AcClientConnection::AcConnectionStatus c_status;

RWCollectableString m_userName="Administrator", m_password="";

// Make connection to the server

m_connection = new AcClientConnection("","wrongname",

m_userName,m_password);

AcGetUserNames getUsers;

m_sendStatus =m_connection->SendRequest(getUsers, m_timeout);

if (m_sendStatus != AcClientConnection::AC_SEND_OK) {

AcMessageSendError error =

connection->GetMessageSendError(getUsers);

const char* string = AcErrorSeverityToString(error.GetErrorSeverity());

cerr <<	"MESSAGE REPLY ERROR" << '\n' <<

"        Severity    : " << string << '\n' <<

"        Name        : " << error.GetErrorName() << '\n' <<

"        Location    : " << error.GetErrorLocation() << '\n' <<

"        Description : " << error.GetErrorDescription() << endl;

} else // . . . do something with the names of users


Member functions of AcMessageSendError

AcMessageSendError::GetErrorSeverity

AcMessageSendError::GetErrorName

AcMessageSendError::GetErrorListName

AcMessageSendError::GetErrorLocation

AcMessageSendError::GetErrorDescription


AcMessageSendError::GetErrorSeverity

Indicates the seriousness of the error.

Syntax

AcErrorSeverity GetErrorSeverity() const

Description

Returns the severity of the message send error. AcErrorSeverity is an enumerated type with the following values:

•	AC_ERROR_SEVERITY_NO_ERROR

•	AC_ERROR_SEVERITY_WARNING

•	AC_ERROR_SEVERITY_ERROR_RETRYABLE

•	AC_ERROR_SEVERITY_ERROR_NOT_RETRYABLE

•	AC_ERROR_SEVERITY_FATAL

For more information, see Error severity.


AcMessageSendError::GetErrorName

Retrieves the name of the message send error.

Syntax

RWCollectableString GetErrorName() const

Description

Returns the name of the error reported by the server. The name is a text string that states the generic problem and segments the problem into message errors and server errors. For more information, see Error name.


AcMessageSendError::GetErrorListName

Retrieves the name of the list of messages related to the error.

Syntax

RWCollectableString GetErrorListName() const

Description

Returns the name of a list of messages that apply to an error. The error list name is the name of the property list used, if one was used, when a server error occurred. Most error lists are private server member data.

If AC_SERVER_ERROR_ILLEGAL_VALUE, the generic error name, is returned, there are multiple values, representing more than one error message to be examined. The text string name returned by this function identifies the error list associated with the problem.

Although error lists are part of the Report Server internal structure, their names can often give clues to the nature of the problem. For example, if the error list is AC_OBJECT_ID and the error description is Object not found, you can infer the server could not find an object with the specified ID.

For more information, see Interpreting status and error messages.


AcMessageSendError::GetErrorLocation

Returns either the name of the server procedure related to the error or the location of the error, such as the machine name.

Syntax

RWCollectableString GetErrorLocation() const

Description

Returns either the name of the server procedure that was executing when the error occurred or other information for analyzing the problem. For example, in the case of a failed connection, this function returns the name of the machine where the connection procedure was executing. Provide this information to Technical Support should you need to report a problem.


AcMessageSendError::GetErrorDescription

Retrieves some information about the error.

Syntax

RWCollectableString GetErrorDescription() const

Description

Returns a plain text description of the error. If the error is severe, report this message to the application user or system administrator. It is also a valuable analysis tool when combined with the other error messages in AcMessageSendError.


AcNotice

Member functions of AcNotice

Represents notices of operation status.

Constructor

This class has default and copy constructors.

Description

AcNotice objects represent a notice sent from the Report Server system and received asynchronously by the client. Notices describing the status of a requested operation display in the Completed folder of the Report Encyclopedia or are sent in an email message. The following notices are defined for operation status:

•	completion of a request

•	failure of a request

•	notice of errors, if any exist, in the execution or printing of an object

Public member functions

Member function	Description
GetInformation	Retrieves a description of the event.


Member functions of AcNotice

AcNotice::GetInformation


AcNotice::GetInformation

Retrieves a description of the event.

Syntax

RWOrdered GetInformation() const

Description

Returns an ordered list of AcProperty objects that describe the target of the event, what and who caused it, and other information. When you no longer need the list, delete its values.

The list of values is a copy, so modifying the information does not affect the notice. The contents of the information are defined specifically for each type of event.


AcOperationNotice

Member functions of AcOperationNotice

Represents a message from the factory server regarding the success or failure of an operation.

Description

Creates a message to get the operation status of a request, identify the request and the report item resulting from the requested operation, and to retrieve information about operation failures if they occur. This class uses the AcMessageSendError to encapsulate the location, error name or list of error names, severity, and other information about the success of operations. Notifications display in the Completed folder of the Report Encyclopedia or are sent to a group of users by email.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetErrorInformation	Returns an AcMessageSendError object with descriptive information about failures.
GetOperationStatus	Returns an AcOperationStatus object indicating an error, warning, or success.
GetRequestID	Identifies the request associated with this notice, by object ID.
GetRequestName	Identifies the request associated with this notice by name.
GetOutputObjectID	Identifies the output object of the request associated with this notice.
GetOutputObjectName	Returns the name of the output object associated with this notice.
GetOutputObjectVersion Number	Returns the version number of the output object associated with the notice.
GetOutputObjectType	Returns the type of the output object, such as ROI, associated with the notice.
GetStartDateAndTime	Retrieves the date and time of the request associated with this notice.


Member functions of AcOperationNotice

AcOperationNotice::GetErrorInformation

AcOperationNotice::GetOperationStatus

AcOperationNotice::GetRequestID

AcOperationNotice::GetRequestName

AcOperationNotice::GetOutputObjectID

AcOperationNotice::GetOutputObjectName

AcOperationNotice:: GetOutputObjectVersionNumber

AcOperationNotice::GetOutputObjectType

AcOperationNotice::GetStartDateAndTime


AcOperationNotice::GetErrorInformation

Retrieves descriptive information about failures.

Syntax

AcMessageSendError GetErrorInformation() const

Return value

Returns the error message if a failure occurred. The AcMessageSendError object can encapsulate the location, error name or list of error names, severity, and other descriptive information.


AcOperationNotice::GetOperationStatus

Retrieves the indicator of success or failure of the operation.

Syntax

AcOperationStatus GetOperationStatus() const

Description

Returns the status of the operation. The enum AcOperationStatus has the following values:

AC_OPERATION_OK

AC_OPERATION_WARNING

AC_OPERATION_WARNING_LAST

AC_OPERATION_ERROR

The AC_OPERATION_WARNING_LAST message indicates the most severe warning message. A failure condition returns AC_OPERATION_ERROR.


AcOperationNotice::GetRequestID

Identifies the request associated with this notice by object ID.

Syntax

RWCollectableString GetRequestID() const

Description

There are two ways to specify the request associated with the notice: by ID or by name. This function accesses the ID.


AcOperationNotice::GetRequestName

Identifies the request associated with this notice by name.

Syntax

RWCollectableString GetRequestName() const

Description

There are two ways to specify the request associated with this notice: by ID or by name. This function accesses the name.


AcOperationNotice::GetOutputObjectID

Identifies the output object of the request associated with this notice.

Syntax

RWCollectableString GetOutputObjectID() const

Description

Returns the ID of the output object associated with this notice. For example, a user is set up to receive notification of completed requests for a report called forecast. This function returns the ID of forecast.roi when it prints.


AcOperationNotice::GetOutputObjectName

Returns the name of the output object associated with this notice.

Syntax

RWCollectableString GetOutputObjectName() const

Description

Identifies the output object associated with this notice by name. For example, a user is set up to receive notification of completed requests for a report called forecast. This function returns the name, forecast.roi, when it prints.


AcOperationNotice:: GetOutputObjectVersionNumber

Returns the version number of the output object associated with the notice.

Syntax

Unsigned long  GetOutputObjectVersionNumber() const


AcOperationNotice::GetOutputObjectType

Retrieves the type of the object associated with this notice.

Syntax

RWCollectableString GetOutputObjectType() const

Description

Returns the type of the output object associated with this notice. An output object is a return value of the request. ROI and ROW are actual results of requests, so they are the only types used as output object types. For more information on object types, see type_if_not_found.


AcOperationNotice::GetStartDateAndTime

Retrieves the date and time of the request associated with this notice.

Syntax

RWCollectableTime GetStartDateAndTime() const

Description

Returns the start date and time of the request associated with this notice. The information is in UTC (Universal Time Code) format: 04/23/97 13:18:15.


AcPersistentObject

Example   Member functions of AcPersistentObject

Opens access to an existing persistent object or creates a new persistent object in the Report Encyclopedia.

Syntax

AcPersistentObject obj(*con, obj, AC_VERSION_LATEST, 0, "ROX", status);

Description

AcPersistentObject encapsulates the processes needed to administer and manipulate reports and folders. A server manages persistent objects on a machine. AcPersistentObject member functions invoke multiple message classes to implement a single task.

Return value

AcPersistentObject functions return the result of the operation as AcOperationStatus, an enumerated data type with the following members:

0 = AC_OPERATION_OK

1 = AC_OPERATION_WARNING

2 = AC_OPERATION_WARNING_LAST

3 = AC_OPERATION_ERROR

The AC_OPERATION_WARNING_LAST message indicates the most severe warning message. A failure condition returns AC_OPERATION_ERROR. If an AcPersistentObject function fails, call AcPersistentObject::GetLastMessageSendError to get information.


Example

This example shows construction of a directory in the Report Encyclopedia. AcOperationStatus is returned by reference in status. The AcPersistentObject object, obj, is used to call GetTree, which traverses the contents of the directory.

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, (fromDirectory.length() ?

fromDirectory : (RWCollectableString)"/"),

AC_VERSION_LATEST, 0, "", status);

AcProperty tree = obj.GetTree( 0, status);


AcPersistentObject constructors

Example

The AcPersistentObject class has forms of the constructor to initialize a persistent object that usually represents a folder or specific version of a report item.

Syntax

AcPersistentObject(const AcClientConnection& client_connection,

 	const RwCollectableString& 	object_id,

AcOperationStatus& 	operation_status)

AcPersistentObject(const AcClientConnection& client_connection,

 	const RwCollectableString&	object_name,

AcVersionType	versionType,

unsigned long 	versionNumber,

const RwCollectableString&	type_if_not_found,

AcOperationStatus& 	operation_status)

AcPersistentObject(const AcClientConnection& client_connection,

 	const RwCollectableString& object_id)

Description

The first two constructors return the result of the operation by reference with AcOperationStatus. Checking the connection is optional. If you don't want to check the status of the operation, use the third constructor.

If you pass the object name instead of the id, specify the following parameters:

•	version type with predefined constants

•	version number or zero

•	type of object with predefined constants or an empty string

Constructor parameters

client_connection

The AcClientConnection object that the client application uses to communicate with the Report Server system.

object_id

The global unique ID of a persistent object that is independent of its name and location.

object_name

The hierarchical path and file name for the object in the Report Encyclopedia. In the Windows environment, specify the Report Encyclopedia input object name file in one of the following ways:

"/Western Region/forecast.roi"

or

"rotp://MyServer/Western Region/forecast.roi"

For more information, see Referring to files--Windows environment.

version_type

A classification of this iteration of a report object. By default, the latest version of the object is used. version_type is an AcVersionType, which defines the following enumerated constants:

Value	Meaning
AC_VERSION_LATEST	The most recent version of the object, which is the default version type.
AC_VERSION_LATEST_ DEVELOPMENT	The version that has been flagged by a call to SetDevelopmentStatus as a development version.
AC_VERSION_LATEST_ RELEASED	The version that has been flagged by a call to SetDevelopmentStatus as a released version.
AC_VERSION_OLDEST	The initial version of the object.
AC_VERSION_SPECIFIC	A particular version number of the object is specified with the next parameter, version_number.
version_number

A number that augments a file name to guarantee the uniqueness of file names for all versions of a report object. Pass a zero unless you use the parameter AC_VERSION_SPECIFIC for the version_type. Passing a nonzero number specifies the specific version number of the object. Use AC_VERSION_LATEST_DEVELOPMENT and AC_VERSION_LATEST_RELEASED to specify objects stamped as such, regardless of the version number.

type_if_not_found

To create another version of an object in the encyclopedia with the same name or ID as this object, pass an empty string (""). To create a brand new object of the type specified by type_if_not_found, pass one of the following strings:

Object types
Enumeration constant	String	Comment
AC_OBJECT_TYPE_DIRECTORY	"Directory"	Path of a report item.
AC_OBJECT_TYPE_ROV	"ROV"	Parameter value.
AC_OBJECT_TYPE_ROD	"ROD"	Design.
AC_OBJECT_TYPE_ROL	"ROL"	Libraries.
AC_OBJECT_TYPE_ROX	"ROX"	Executable.
AC_OBJECT_TYPE_ROI	"ROI"	Report document.
AC_OBJECT_TYPE_BASIC	"Basic"	Basic source code document.
AC_OBJECT_TYPE_ROW	"ROW"	Web documents.
AC_OBJECT_TYPE_ROP	"ROP"	Report parameters. An empty ROV. Internal.
AC_OBJECT_TYPE_HTML	"HTML"	Hypertext documents.
AC_OBJECT_TYPE_BITMAP	"Bitmap"	Bitmaps.
User-defined types can be added to the Encyclopedia.

operation_status

A value that describes the operating status after an attempt to open or create a persistent object.For more information, see Return value.

Operators

The API defines assignment, equality, and inequality operators.

Public member functions

The member functions fall into five categories, as shown in the following table:

Programming task	Member function
Event notification and security	AddChannelNameEventTypes, AddGroupNameEventType, AddUserNameEventType, DeleteChannelNameEventTypes, DeleteChannelNameEventType, DeleteEventTypes, DeleteGroupNameEventType, DeleteUserNameEventType, GetChannelNameEventTypes, GetEventChannelNames, GetEventGroupNames, GetEventUserNames, GetGroupNameEventTypes, GetRoleNamePrivilegeTypes, GetUserNameEventTypes, GetUserNamePrivilegeTypes
Object access	CloseStream, GetElements, GetReadStream, Read, ReadToLocalFile, SetReadLock, SetWriteLock, UnsetReadLock, UnsetWriteLock, Write
Object properties	AddDependent, AddProperty, DeleteDependent, DeleteDependents, DeleteProperties, DeleteProperty, DeletePropertyList, GetDependents, GetBasicProperties, GetCreationDateAndTime, GetDependentOn, GetDevelopmentStatus, GetID, GetLastModificationDateAndTime, GetLastModificationUserName, GetName, GetOwner, GetPropertyList, GetPropertyListNames, GetSize, GetType, GetVersion, GetVersionNumber, GetVersions, SetDevelopmentStatus, SetOwner
Default printing options	GetDefaultPrinterName, GetPrinterOptionDefaults, SetDefaultPrinterName, SetPrinterOptionDefaults
Directory services	Delete, Copy, GetBaseName, GetContainedObjects, GetPath, GetTree, Move


Example

This example demonstrates the use of the type_if_not_found parameter. The constructor passes an empty type string because the report called forecast.roi already exists.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection,

objectName, AC_VERSION_LATEST, 0, "", status);

This example shows how to construct an AcPersistent object to access an existing directory called Eastern Region.

RWCollectableString dirName = "Eastern Region";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*connection,

dirName, AC_VERSION_LATEST, 0,

AC_OBJECT_TYPE_DIRECTORY, status);

This example shows how to create a local copy of an executable file called forecast.rox that is stored in the Eastern Region folder. To create a new Report Encyclopedia version, the application must use the write member function to transfer this copy to the Report Encyclopedia.

// Executable in encyclopedia

RWCollectableString rxName= "/Eastern Region/forecast.roi";

// Create a new version of detail.rox

AcPersistentObject* rxObject = new AcPersistentObject( *connection,

rxName, AC_VERSION_LATEST , 0, "", status );


Member functions of AcPersistentObject

AcPersistentObject::AddChannelNameEventType

AcPersistentObject::AddDependent

AcPersistentObject::AddProperty

AcPersistentObject::AddGroupNameEventType

AcPersistentObject::AddUserNameEventType

AcPersistentObject::CloseStream

AcPersistentObject::Copy

AcPersistentObject::Delete

AcPersistentObject::DeleteChannelNameEvent Types

AcPersistentObject::DeleteChannelNameEventType

AcPersistentObject::DeleteDependent

AcPersistentObject::DeleteDependents

AcPersistentObject::DeleteEventTypes

AcPersistentObject::DeleteGroupNameEventType

AcPersistentObject::DeleteGroupNameEventTypes

AcPersistentObject::DeleteProperties

AcPersistentObject::DeleteProperty

AcPersistentObject::DeletePropertyList

AcPersistentObject::GetBaseName

AcPersistentObject::GetBasicProperties

AcPersistentObject::GetChannelNameEventTypes

AcPersistentObject::GetContainedObjects

AcPersistentObject::GetCreationDateAndTime

AcPersistentObject::GetDefaultPrinterName

AcPersistentObject::GetDependents

AcPersistentObject::GetDependentOn

AcPersistentObject::GetDevelopmentStatus

AcPersistentObject::GetElements

AcPersistentObject::GetEventChannelNames

AcPersistentObject::GetEventGroupNames

AcPersistentObject::GetEventUserNames

AcPersistentObject::GetGroupNameEventTypes

AcPersistentObject::GetID

AcPersistentObject::GetLastMessageSendError

AcPersistentObject::GetLastModificationDateAndTime

AcPersistentObject::GetLastModificationUserName

AcPersistentObject::GetName

AcPersistentObject::GetOwner

AcPersistentObject::GetPath

AcPersistentObject::GetPrinterOptionDefaults

AcPersistentObject::GetPropertyList

AcPersistentObject::GetPropertyListNames

AcPersistentObject::GetReadStream

AcPersistentObject::GetRoleNamePrivilegeTypes

AcPersistentObject::GetSize

AcPersistentObject::GetTree

AcPersistentObject::GetType

AcPersistentObject::GetUserNameEventTypes

AcPersistentObject::GetUserNamePrivilegeTypes

AcPersistentObject::GetVersionNumber

AcPersistentObject::GetVersion

AcPersistentObject::GetVersions

AcPersistentObject::Move

AcPersistentObject::Read

AcPersistentObject::ReadToLocalFile

AcPersistentObject::SetDefaultPrinterName

AcPersistentObject::SetDevelopmentStatus

AcPersistentObject::SetOwner

AcPersistentObject::SetPrinterOptionDefaults

AcPersistentObject::SetReadLock

AcPersistentObject::SetWriteLock

AcPersistentObject::UnsetReadLock

AcPersistentObject::UnsetWriteLock

AcPersistentObject::Write


AcPersistentObject::AddChannelNameEventType

Add an event type that the specified channel can observe. Events cannot be duplicated for one channel.

Syntax

AcOperationStatus
AddChannelNameEventType(const String& channel_name,
const String& event_type) const

channel_name

The name of the channel that can observe the event.

event_type

The type of event to observe.


AcPersistentObject::AddDependent

See also

Adds a dependent to this object.

Syntax

AcOperationStatus AddDependent(const AcPersistentObject& object)

object

The object id of the object to add as a dependent to this object. The server automatically creates a unique object id when a new object is instantiated, which you can retrieve with the GetID member function of this class. The object id is a character string.

Description

This function adds a relationship between two specific versions of report items, such as a report executable (ROX) and report document (ROI) objects. Only report objects can have dependents and dependents cannot be duplicated.

The dependency between a document (ROI) and executable (ROX) is set by Actuate when you run an executable in the Report Encyclopedia. The dependency between a parameter values file and the ROX is set by Actuate when you create and save parameters in the Report Encyclopedia, but when you copy an ROI from a local system to the Report Encyclopedia, you must also copy the ROX and set up a dependency. Objects dependent on the original object are not dependent on the copy.


See also

AcPersistentObject::Copy


AcPersistentObject::AddProperty

Appends a property to the end of the named public property list.

Syntax

AcOperationStatus AddProperty(
const RWCollectableString& list_name,
const AcProperty& property)

list_name

The public property list to which the new property is added. Clients can use the property lists to store user-defined information about the object. Unlike the private lists, the server does not act on public lists.

property

The property to add, which can contain any string or list of strings. For example, the strings can describe a custom object property, such as a privilege, or programmer comments. The property has no particular server rules governing it.

Description

All persistent objects have named property lists that are used to store public and private information, such as administrative information, about the object. This function adds properties to the public list. The named lists can use variable length strings for their names. The function fails if:

•	a property with the same name already exists.

•	the version of the list in the server does not match the cached version in this client object.

For more information, see Persistent object class.


AcPersistentObject::AddGroupNameEventType

Adds an event to the list of events that can be observed by a notification group.

Syntax

AcOperationStatus AddGroupNameEventType(
const RwCollectableString&	group_name,
const RwCollectableString&	event_type) const

group_name

The name of the notification group that can observe the specified events from this object.

event_type

The type of event reported. Currently, the only event supported is object operation completed, specified as the character string "Operation Status".

Description

AddGroupNameEventType adds an event to the object's event list. Specify the notification group that can observe the event. Duplicate events cannot be added to the same group. Currently, the only event supported is object operation completed. For more information on events, see Report Encyclopedia events.


AcPersistentObject::AddUserNameEventType

Adds the specified event to the list of events that can be observed by the specified user.

Syntax

AcOperationStatus AddUserNameEventType(
const RwCollectableString&	user_name,
const RwCollectableString&	event_type) const

user_name

The name of the user who can observe the specified events from this object.

event_type

The type of event reported. Currently, the only event supported is object operation completed, specified as the character string "Operation Status".

Description

Adds an event to the object's event list. Specify the user who can observe the event. Duplicate events cannot be added for the same user. Currently the only event supported is object operation completed, specified as the character string, "Operation Status". For more information on events, see Report Encyclopedia events.


AcPersistentObject::CloseStream

Closes the given datastream for reading or writing.

Syntax

void CloseStream(streambuf* stream, AcOperationStatus& operationStatus)

stream

A pointer to the buffered stream returned from GetReadStream.

Return value

CloseStream returns by reference an operation status message, described in Return value.


AcPersistentObject::Copy

See also

Makes a copy of this persistent object.

Syntax

AcOperationStatus Copy(const RwCollectableString& object_name,
RWBoolean all_versions = FALSE) const

object_name

The full name, hierarchical path name and extension, of the duplicated object.

all_versions

If TRUE, copy all versions of objects corresponding to this object. If FALSE, copy the persistent object corresponding to the object ID of this object and the objects it contains.

Description

Copies either a single version or all versions of this object to the specified object name (hierarchical path and file name). If the new name resolves to a directory, this function copies the object or set of objects into the directory. If one or more objects with the same full name already exist and do not resolve to a directory, this function creates a new version of the target object.

If the report item is copied to a directory path that does not exist, the operation fails. The copies of objects are dependent on the same objects as the original objects. Objects dependent on the original object are not dependent on the copy. The user copying report items owns the copies.


See also

AcPersistentObject::DeleteDependent


AcPersistentObject::Delete

Example   See also

Deletes this persistent object.

Syntax

AcOperationStatus Delete (RWBoolean all_versions = FALSE,
RWBoolean recursive = FALSE)

all_versions

If TRUE, delete all versions of objects corresponding to this object. If FALSE, delete only the persistent object corresponding to the object ID of this object.

recursive

If TRUE, delete this object and all contained objects. If FALSE, or if this object contains any objects, the deletion fails. This behavior applies to all versions of the object if all versions are being deleted.

Description

Parameters specify deletion of all of the versions or a specific version only. A report item cannot be deleted as long as it has dependent versions, such as the dependency between ROX and ROI objects. The dependent versions must be deleted first.


Example

The following example deletes the latest version of forecast.roi in the Eastern Region folder.

RWCollectableString object = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, object, AC_VERSION_LATEST, 0,

  "", status);

status = obj.Delete();


See also

AcPersistentObject::DeleteDependent


AcPersistentObject::DeleteChannelNameEvent Types

Deletes all of the events the specified channel can observe. The call returns an AcOperationStatus, a nested enum that indicates the success, failure, or other status of the operation.

Syntax

AcPersistentObject::AcOperationStatus
DeleteChannelNameEventTypes(const RWCollectableString& channel_name)


AcPersistentObject::DeleteChannelNameEventType

Deletes the specified event type of the specified channel. The call returns an AcOperationStatus, a nested enum that indicates the success, failure, or other status of the operation.

Syntax

AcPersistentObject::AcOperationStatus
DeleteChannelNameEventType(const RWCollectableString& channel_name, const RWCollectableString& event_type)

channel_name

The name of the channel, a text string.

event_type

The type of event reported, such as object moved, renamed, copied, read, and updated. Currently, the only event supported is object operation completed, specified as the character string "Operation Status".


AcPersistentObject::DeleteDependent

Deletes the specified object from the list of dependents for this object.

Syntax

AcOperationStatus DeleteDependent(const AcPersistentObject& object)

object

The dependent object to delete.

Description

The dependency between a document (ROI) and executable (ROX) is set by Actuate when you run an executable in the Report Encyclopedia. The dependency between a parameter values file (ROV) and the ROX is set by Actuate when you create and save an ROV in the Report Encyclopedia. When you copy an ROI from a local system to the Report Encyclopedia, you must copy the ROX and set up a dependency. A report item, such as an ROX, cannot be deleted as long as it has a file dependent on it. Use this function to delete the dependent file.


AcPersistentObject::DeleteDependents

See also

Deletes all of this object's dependents.

Syntax

AcOperationStatus DeleteDependents()

Description

This function deletes dependencies between objects in the Report Encyclopedia. The dependency between a document (ROI) and executable (ROX) is set by Actuate when you run an executable in the Report Encyclopedia. The dependency between a parameter values file (ROV) and the ROX is set by Actuate when you create and save an ROV in the Report Encyclopedia, but when you copy an ROI from a local system to the Report Encyclopedia, you must copy the ROX and set up a dependency. A dependency must also be set up between ROV and ROX files. Report items cannot be deleted as long as there are files dependent on them. Use this function to delete dependent files.


See also

AcPersistentObject::DeleteDependent


AcPersistentObject::DeleteEventTypes

Deletes all of this object's event information.

Syntax

AcOperationStatus DeleteEventTypes()

Description

DeleteEventTypes deletes all event information for this object. The event, object operation completed (specified as the string "Operation Status") is the only supported event. Once deleted, this object no longer reports operation complete to users or groups. For more information on events, see Report Encyclopedia events.


AcPersistentObject::DeleteGroupNameEventType

See also

Deletes the specified event from the list of events that can be observed by the specified notification group.

Syntax

AcOperationStatus
DeleteGroupNameEventType(const RwCollectableString& group_name,
const RwCollectableString& event_type)

group_name

The name of the group.

event_type

The type of event reported. Currently, the only event supported is object operation completed, specified as the character string "Operation Status".


See also

AcPersistentObject::AddGroupNameEventType


AcPersistentObject::DeleteGroupNameEventTypes

Deletes all events from the list of events for this object that can be observed by the specified notification group.

Syntax

AcOperationStatus DeleteGroupNameEventTypes(const RwCollectableString& groupname)

groupname

The name of the group.


AcPersistentObject::DeleteProperties

Deletes all of this object's properties from the public property lists.

Syntax

AcOperationStatus DeleteProperties()

Description

Public property lists contain user-defined properties that have no effect on server operations. After completion, the object has no public properties. For more information, see Public object properties.


AcPersistentObject::DeleteProperty

Deletes a property from the public property list.

Syntax

AcOperationStatus
DeleteProperty(const RwCollectableString& list_name, const AcProperty& property_name)

list_name

The name of the property list containing the property to be deleted.

property_name

The name of the property to delete.

Description

Deletes the first property named property_name from the specified public property list. DeleteProperty does not write-lock the object during the operation. This means that the object can change in the middle of the delete. If this happens, the operation fails.

The function fails if the version of the state of the property list in the encyclopedia does not match the state of the cached version in this client object.


AcPersistentObject::DeletePropertyList

Deletes all of the values of the specified public property list.

Syntax

AcOperationStatus DeletePropertyList(const RwCollectableString& list_name)

list_name

The name of the property list to delete.

Description

Deletes all the values of the specified public property list, then removes the list. DeletePropertyList does not write-lock the object during operation. This means that the object can change in the middle of the delete. If this happens the operation fails. For more information, see Public object properties.


AcPersistentObject::GetBaseName

Returns the name of this object, without the path.

Syntax

RwCollectableString GetBaseName(AcOperationStatus& operation_status) const

Description

The base name is the full file name, less any path information.


AcPersistentObject::GetBasicProperties

Retrieves the fundamental properties of this object.

Syntax

void GetBasicProperties
(RwCollectableString& 	type,
unsigned long& 	size,
RwCollectableString& 	owner,
RWTime& 	creationDateAndTime,
RwCollectableString& 	lastModificationUserName,
RWTime& 	modificationDateAndTime,
AcOperationStatus& 	operation_status) const

type

One of the following object types:

Enumeration constant	String	Comment
AC_OBJECT_TYPE_DIRECTORY	"Directory"	Path of a report item.
AC_OBJECT_TYPE_ROV	"ROV"	Parameter value.
AC_OBJECT_TYPE_ROD	"ROD"	Design.
AC_OBJECT_TYPE_ROL	"ROL"	Libraries.
AC_OBJECT_TYPE_ROX	"ROX"	Executable.
AC_OBJECT_TYPE_ROI	"ROI"	Report document.
AC_OBJECT_TYPE_BASIC	"Basic"	Basic source code document.
AC_OBJECT_TYPE_ROW	"ROW"	Web documents.
AC_OBJECT_TYPE_ROP	"ROP"	Report parameters. An empty ROV. Internal.
AC_OBJECT_TYPE_HTML	"HTML"	Hypertext documents.
AC_OBJECT_TYPE_BITMAP	"Bitmap"	Bitmaps.
size

The size of the object in bytes.

owner

The owner of the object. The owner is the object's creator unless another owner has been designated.

creationDateAndTime

The date and time in UTC (Universal Time Code) of creation. For example,
04/23/97 13:18:15

lastModificationUserName

The name of the user who last modified the object.

modificationDateAndTime

The date and time of the last modification in UTC format.

operation_status

The status of the operation. AcPersistentObject functions return the result of the operation as AcOperationStatus, an enumerated data type with the following members:

0 = AC_OPERATION_OK

1 = AC_OPERATION_WARNING

2 = AC_OPERATION_WARNING_LAST

3 = AC_OPERATION_ERROR

Description

Returns by reference the fundamental properties of this object, for example

•	type--ROX

•	size--23040

•	owner--administrator

•	date and time created--04/23/97 13:18:15

•	last modified by--administrator

•	last modified--04/29/97 12:10:05

The Report Server uses the properties to manage items in the Report Encyclopedia.


AcPersistentObject::GetChannelNameEventTypes

Gets the list of event types that this channel can observe. Returns an empty list if there is an error. Check the access status if an error occurs.

Syntax

Ordered GetChannelNameEventTypes
(const String&      channel_name,
AcOperationStatus& operation_status) const

channel_name

The name of the channel to get the events for.

operation_status

Returns the status of the operation.

Description

GetChannelNameEventTypes returns a list of the event types that the specified channel can observe on this object. Currently, the only event supported is object operation completed, specified as the character string "Operation Status".


AcPersistentObject::GetContainedObjects

Example

Retrieves the list of AcPersistentObject objects contained in a folder.

Syntax

RWOrdered GetContainedObjects(AcOperationStatus& operation_status)

Description

Returns an ordered polymorphic collection of objects contained in this object.   When you no longer need the collection, delete it.


Example

The following function calls GetContainedObjects to get a list of persistent objects (report items) from the Eastern Region folder. The test code uses additional functions of persistent object to get the names, types, versions, and IDs from the list of objects this function returns.

RWCollectableString directoryName = "/Eastern Region";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj( *m_connection,

  directoryName,

  AC_VERSION_LATEST, 0, "", status);

// return contained persistent objects

RWOrdered objects = obj.GetContainedObjects(status);

// ******************test code************************

// cycle through objects and send information to standard output

RWOrderedIterator   iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  cout << endl << "Object Name: " << object->GetName(status) <<

    " Type: " << object->GetType(status) << " Version: " <<

    object->GetVersionNumber(status) << endl <<

    "   ID: " << object->GetID(status) << endl;

}

This example produces output similar to the following:

Object Name: /Eastern Region/abc.rox Type: ROX Version: 1

   ID: 128.1.1.2:_1814_2010180_b4d9e7b8_6e

Object Name: /Eastern Region/def.rox Type: ROX Version: 1

   ID: 128.1.1.2:_2e_2010180_b4db9aae_6e


AcPersistentObject::GetCreationDateAndTime

Example

Retrieves the date and time of the creation of this object, in UTC format.

Syntax

RWTime
GetCreationDateAndTime(AcOperationStatus& operation_status) const

Return value

The returned information is in UTC (Universal Time Code) format: 04/23/97 13:18:15


Example

The following example opens a persistent object called objectName, gets a list of all versions, and then gets the creation dates and prints them to standard output.

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse the list of reports and send the date and time to standard output

while (object = (AcPersistentObject*)iterator()) {

cout << object->GetCreationDateAndTime(status) << endl;

}


AcPersistentObject::GetDefaultPrinterName

Returns the name of the default printer for this persistent object.

Syntax

RwCollectableString GetDefaultPrinterName(AcOperationStatus& operation_status) const

Description

The default printer name is the printer used if the request did not specify a printer. This setting overrides the user and system default printers. For more information, see Report Encyclopedia events.


AcPersistentObject::GetDependents

Example

Returns a list of objects of type AcPersistentObject that depend on this object.

Syntax

RWOrdered GetDependents(AcOperationStatus& operation_status) const

Description

The dependency between a document (ROI) and executable (ROX) is set by Actuate when you run an executable in the Report Encyclopedia. The dependency between a parameter values file (ROV) and the ROX is set by Actuate when you create and save an ROV in the Report Encyclopedia, but when you copy an ROI from a local system to the Report Encyclopedia, you must copy the ROX and set up a dependency. A dependency also has to be set up between ROV and ROX files. This function ascertains which dependencies are set up.

When you no longer need the list returned by this function, delete it.


Example

This following example gets a list of dependents for all versions of the report executable forecast.rox in the Eastern Region folder and prints their names to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

// list all the versions

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse the list

while (object = (AcPersistentObject*)iterator()) {

  RWOrdered dependents = object->GetDependents(status);

  RWOrderedIterator depsIterator(dependents);

  AcPersistentObject* depObject;

    while (depObject = (AcPersistentObject*)depsIterator()) {

    cout << "\tDependents ID: " << depObject->GetName(status) << endl;

    }

}


AcPersistentObject::GetDependentOn

Example

Retrieves a list of the objects of type AcPersistentObject that this object depends on.

Syntax

RWOrdered GetDependentOn(AcOperationStatus& operation_status) const

Description

This function returns a list of objects that this object depends on, such as specific versions of report items. You must specifically delete the list of objects when you no longer need it.

Some report files depend on the existence of other report files. For example, an ROI and ROV depend on an ROX. When you open a report for viewing or printing, Actuate runs the ROX, which generates the report instance (ROI), which you then view or print. Only report objects can have dependents and dependents cannot be duplicated.


Example

This example takes the list returned by GetDependentOn and iterates through it, sending the name of the objects that forecast.roi depends on to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Creation Date and Time: "

    << object->GetCreationDateAndTime(status) << endl;

  cout << "Object Dependent On List" << endl;

  RWOrdered dependentOn = object->GetDependentOn(status);

  RWOrderedIterator depOnIterator(dependentOn);

  AcPersistentObject* depOnObject;

    while (depOnObject = (AcPersistentObject*)depOnIterator()) {

      cout << "\tDependent On ID: " << depOnObject->GetName(status) << endl;

    }

  }


AcPersistentObject::GetDevelopmentStatus

See also

Ascertains the status of the object, either development or released.

Syntax

RWBoolean
GetDevelopmentStatus(AcOperationStatus& operation_status) const

Return value

TRUE if the object is a development version, FALSE if the object is a released version.


See also

AcPersistentObject::SetDevelopmentStatus


AcPersistentObject::GetElements

Example

Retrieves a list of streams associated with a report executable in the encyclopedia. Does not access elements in a file system report item.

Syntax

RWOrdered GetElements(AcOperationStatus& operation_status)

Description

Returns a list of streams that are the output of this object, such as the following: ROP, ROX, Image, and Contents. Use the retrieved elements as input to the following functions: GetReadStream and ReadToLocalFile. When you no longer need the list of streams, delete it.


Example

This example retrieves the elements of the file forecast.rox. The example:

1	Creates and copies a persistent object.

2	Sets a read lock on the copy.

3	Produces a list of elements.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

// Make connection (m_connection) to the server -- not shown

// check status of connection -- not shown

AcPersistentObject::AcOperationStatus status;

AcPersistentObject myObj(   *m_connection, objectName,

AC_VERSION_LATEST, 0, "ROX", status);

cout << "Object Name: " << objectName << endl;

if (status != AcPersistentObject::AC_OK) {

cerr << "Could not \"open\" object." << endl;

return;

}

AcPersistentObject obj;

obj=AcPersistentObject(myObj);

if((status = obj.SetReadLock()) != AcPersistentObject::AC_OK){

cerr << " Unable to set Read Lock on Object : " <<

(char*)objectName.data() << endl;

return;

}

//  List all the elements

RWOrdered elementList =obj.GetElements(status );

if (status != AcPersistentObject::AC_OK) {

cerr << "Could not \"List  Elements\" object." << endl;

return;

}

else {

RWOrderedIterator l_iter((RWOrdered&) elementList);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

}

}

if((status = obj.UnsetReadLock()) != AcPersistentObject::AC_OK){

cerr << " Unable to unset Read Lock on Object : " <<

(char*)objectName.data() << endl;

}

This example produces the following output, a list of elements, for a file called forecast.rox in the Eastern Region folder of the Report Encyclopedia.

Connected To Server With  Status  : 0
Object Name: /Eastern Region/forecast.rox
ROP
ROX
Image1
Contents


AcPersistentObject::GetEventChannelNames

Returns a list of names of the channels that can observe events on this object.

Syntax

Ordered GetEventChannelNames(AcOperationStatus& operation_status) const

operation_status

Returns the status of the operation.


AcPersistentObject::GetEventGroupNames

Example

Retrieves a list of the names of notification groups that can observe an event on this object.

Syntax

RWOrdered
GetEventGroupNames(AcOperationStatus& operation_status) const


Example

This example gets the list of notification group names for all versions of forecast.roi in the Eastern Region folder, traverses the list, then sends each group name to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection,

objectName, AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse versions

while (object = (AcPersistentObject*)iterator()) {

// get names of groups

RWOrdered groupNames = object->GetEventGroupNames(status);

RWOrderedIterator groupNameIterator(groupNames);

RWCollectableString* groupName;

// traverse and print list of names

while (groupName = (RWCollectableString*)groupNameIterator()) {

cout << "\tGroup Name: " << *groupName << endl;

}

}


AcPersistentObject::GetEventUserNames

Example   See also

Retrieves the names of users who can observe an event for this object.

Syntax

RWOrdered
GetEventUserNames(AcOperationStatus& operation_status) const

Description

Retrieves a list of users who can observe an event on this object. You must delete the list when you no longer need it.


Example

This example gets the list of user names to notify for all the versions of forecast.rox in the Eastern Region folder. It traverses the list, then sends each user name to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection,

objectName, AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse versions

while (object = (AcPersistentObject*)iterator()) {

// get names of users

RWOrdered userNames = object->GetEventUserNames(status);

RWOrderedIterator    userNameIterator(userNames);

RWCollectableString* userName;

while (userName = (RWCollectableString*)userNameIterator()) {

cout << "\tUser Name: " << *userName << endl;

 	 }

}


See also

AcPersistentObject::GetLastMessageSendError


AcPersistentObject::GetGroupNameEventTypes

Retrieves the events that a specified group can observe for this object.

Syntax

RWOrdered GetGroupNameEventTypes (const RwCollectableString& group_name, AcOperationStatus& operation_status) const

group_name

The name of the group that can observe events for this object.

Description

Retrieves a list of the types of events that the specified group can observe on this object. You must specifically delete the list when you no longer need it.


AcPersistentObject::GetID

See also

Returns the global unique ID of this object.

Syntax

RwCollectableString GetID(AcOperationStatus& operation_status) const

Description

GetID accesses the global unique ID of an object. The global unique ID of a persistent object is independent of its name and location.


See also

AcPersistentObject::GetType


AcPersistentObject::GetLastMessageSendError

Retrieves the error information for the last operation to this object.

Syntax

AcMessageSendError GetLastMessageSendError() const

Description

Client applications call this function to get additional error information about AcOperationStatus warnings or errors. The returned object includes the following information:

•	Error severity

•	Error name

•	Error list name

•	Error location

•	Test description

For more information on errors see Interpreting Report Server errors.

Return value

Returns an AcMessageSendError object, which encapsulates information about error conditions for the last operation executed from this object. If there was no error or warning from the last operation, the severity of the AcMessageSendError object is AC_ERROR_SEVERITY_NO_ERROR.


AcPersistentObject::GetLastModificationDateAndTime

Example

Returns the date and time of the last modification to this object.

Syntax

RWTime
GetLastModificationDateAndTime (AcOperationStatus&
operation_status) const


Example

This example accesses all versions of a report called forecast.rox in the Eastern Region folder to print the dates and times of the last modifications.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse the list, printing date and time of last modification

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Last Modification Date and Time: "

    << object->GetLastModificationDateAndTime(status) << endl;

}


AcPersistentObject::GetLastModificationUserName

Example

Returns the name of the user who made the last modification to this object.

Syntax

RwCollectableString GetLastModificationUserName (
AcOperationStatus& operation_status) const


Example

This example gets the name of the user who made the last modification to forecast.rox in the Eastern Region folder.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// traverse the list, printing date and time of last modification

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Last Modification User Name: "

    << object->GetLastModificationUserName(status) << endl;

}


AcPersistentObject::GetName

See also

Returns the full name of this object, including the path.

Syntax

RwCollectableString GetName(AcOperationStatus& operation_status) const


See also

AcPersistentObject::GetType


AcPersistentObject::GetOwner

Example

Retrieves the name of the object's owner.

Syntax

RwCollectableString GetOwner(AcOperationStatus& operation_status) const

Description

Returns the user name of the owner of this object. The default owner of an item is the item's creator. Initially, only the owner and administrator can change the owner of an item. The owner can grant privileges on the item.


Example

This example gets a list of all versions of the forecast.rox, traverses the list, and sends the owner's name to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

// get existing object

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

// all versions

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

// print the owners' names

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Owner: " <<

    object->GetOwner(status) << endl;

}


AcPersistentObject::GetPath

Returns the path of the object without its base name.

Syntax

RwCollectableString GetPath(AcOperationStatus& operation_status) const

Description

Object names consist of path names (the object's location) and the name of the object itself. The name of the object is its base name. The function retrieves the object's path name without its base name.


AcPersistentObject::GetPrinterOptionDefaults

Retrieves the object's default options and certain attributes for the specified printer.

Syntax

AcOperationStatus GetPrinterOptionDefaults(
const RwCollectableString& 	printer_name,
RWOrdered& 	option_defaults,
RWBoolean& 	default_printer_flag) const

printer_name

The name of the printer for this query. The printer must be recognized by the print server, or the operation fails.

option_defaults

An ordered list of properties that describe the following options and attributes of the specified printer:

Option	Property name	Value type
Printer Model - Unix Only	AC_PRINTER_ATTRIBUTE_MODEL	String List (1)
Printer Brand Name - Unix Only	AC_PRINTER_ATTRIBUTE_DESCRIPTION	String
Location	AC_PRINTER_ATRRIBUTE_LOCATION	String
Print to File	AC_PRINTER_OPTION_PRINT_TO_FILE	String
Paper Length	AC_PRINTER_OPTION_PAPER_LENGTH	Integer
Page Range	AC_PRINTER_OPTION_PAGE_RANGE	Integer
Paper Width	AC_PRINTER_OPTION_PAPER_WIDTH	Integer
Form Name	AC_PRINTER_OPTION_FORMNAME	Integer. For more information, see "AC_PRINTER_OPTION_FORMNAME"
Orientation	AC_PRINTER_OPTION_ORIENTATION	String List
Scale	AC_PRINTER_OPTION_SCALE	Integer
Resolution	AC_PRINTER_OPTION_RESOLUTION	String List
Copies	AC_PRINTER_OPTION_COPIES	Integer
Page Size	AC_PRINTER_OPTION_PAGE_SIZE	String List
Paper Tray	AC_PRINTER_OPTION_PAPER_TRAY	String List
Color	AC_PRINTER_OPTION_COLOR	Boolean
Duplex	AC_PRINTER_OPTION_DUPLEX	String List
Collate	AC_PRINTER_OPTION_COLLATE	Boolean
(1) Model names returned by XPrinter, a Bristol Technology printer driver for UNIX.

default_printer_flag

Returns TRUE when the specified printer is the default printer for this object.


AcPersistentObject::GetPropertyList

Retrieves the specified property list for this object.

Syntax

RWOrdered GetPropertyList(const RwCollectableString& list_name,
AcOperationStatus& operation_status) const

list_name

The name of the list to retrieve.

Description

Returns the list of the properties in the specified property list contained in this object. You must delete the list when you no longer need it. The returned property values are copies, so modification of the properties does not affect the object.


AcPersistentObject::GetPropertyListNames

Example

Gets a list of names of all the property lists for this object.

Syntax

RWOrdered GetPropertyListNames(AcOperationStatus& operation_status) const

Description

This function retrieves a list of the names of property lists, which this object uses to store public and private (administrative) information about itself. The meta-list consists of a variable length string for the name of the property list followed by a list of variable length strings (properties). These properties are stored in a repository. The address or key of the item in the repository is the full report name or a global unique object ID.

Return value

Returns a list of names of property lists for this object. Delete the contents of the list when you no longer need it.


Example

The example shows GetPropertyListNames returning a list of property list names for a report called forecast.rox in the Eastern Region folder, and an iterator sending the names to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

RWOrdered names = object->GetPropertyListNames(status);

RWOrderedIterator nameIterator(names);

RWCollectableString* name;

while (name = (RWCollectableString*)nameIterator()) {

cout << "\tProperty Name: " << *name << endl;

}

}


AcPersistentObject::GetReadStream

Retrieves a stream buffer for reading.

Syntax

streambuf* GetReadStream(const RwCollectableString& element_name,	AcOperationStatus& operation_status, const RWBoolean	createNewVersion=FALSE)

element_name

The name of a datastream. Elements can be text, graphics, audio, or other data streams. The maximum length of the name is 32 characters.

Description

Returns a pointer to a buffer for reading the stream specified by element_name. Deleting the stream closes the stream on the server. Read locks are handled implicitly by the stream calls. After a call to GetReadStream to open the stream, remember to call CloseStream.


AcPersistentObject::GetRoleNamePrivilegeTypes

Example

Retrieves a list of privilege types granted to the specified role.

Syntax

RWOrdered GetRoleNamePrivilegeTypes (const RwCollectableString& role_name, AcOperationStatus& operation_status) const

role_name

The name of the role whose privilege list is retrieved.

Description

Returns a list of privilege types granted to the specified role for this object. Delete the contents of the list when you no longer need it. For more information, see Types of privileges.


Example

This example gets the list of privileges that a user named William has for forecast.roi and uses an iterator to send the privileges to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  cout << "Role Name Privilges for " << "William" << endl;

  RWOrdered pri =

    object->GetRoleNamePrivilegeTypes("William", status);

  RWOrderedIterator priIterator(pri);

  RWCollectableString* priv;

  while (priv = (RWCollectableString*)priIterator()) {

    cout << "\tPrivileges : " << *priv << endl;

  }

}


AcPersistentObject::GetSize

Example

Retrieves the size of the file represented by the report object.

Syntax

unsigned long GetSize(AcOperationStatus& operation_status) const

Return value

The current size of the file on success, 0 if an error has occurred.


Example

This example gets the sizes of the all versions of report forecast.roi in the Eastern Region folder.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Size: " << object->GetSize(status) << endl;

}


AcPersistentObject::GetTree

Example

Retrieves a tree of properties that describe the folder hierarchy and contained files.

Syntax

AcProperty GetTree( unsigned long depth,
AcOperationStatus& operation_status) const

depth

The depth of the tree to return. A depth of 0 returns all of the objects below the specified root object. A depth of n returns the n levels of objects below the specified root object. If an object in the nth level is a directory that contains another directory, GetTree returns a dummy property named "FOLDER" to indicate the directory contains at least one directory.

Description

Accesses a tree of objects and their properties. The object properties fall into two categories:

•	basic -- fundamental information used by the server to manage the report items, such as the owner, size, and date of creation.

•	public -- user-defined information, such as a comment.

Use GetTree to identify obsolete reports in a directory for deletion. GetTree returns a single property that has a property list with the following AcProperty values:

Property name	Value type	Description
AC_OBJECT_BASIC_PROPERTY_ NAME	string	Name of the object
AC_OBJECT_BASIC_PROPERTY_ TYPE	string	Type of object, like directory, ROX, or ROI (see pobjtype.h)
AC_OBJECT_BASIC_PROPERTY _VERSION	unsigned integer	Version of the object
AC_OBJECT_BASIC_PROPERTY _SIZE	unsigned integer	Size of the object
AC_OBJECT_BASIC_PROPERTY _OWNER	string	Owner of the object
AC_OBJECT_BASIC_PROPERTY _CREATION_DATE_AND_TIME	unsigned integer	Object creation of UTC date and time in seconds
AC_OBJECT_BASIC_PROPERTY LAST_MODIFICATION_USER_ NAME	unsigned integer	Object modification of UTC date and time in seconds
AC_OBJECT_BASIC_PROPERTY _MODIFICATION_DATE_AND_ TIME	unsigned integer	Object modification of UTC date and time in seconds
AC_OBJECT_BASIC_PROPERTY _CONTAINED_OBJECTS	property list	List of properties contained by this object
AC_OBJECT_PUBLIC_PROPERTIES	property list	A list of public properties where the name of the property is the name of the public property list and the value is the list of properties for that public list
The following is a list of some public properties:.

Property	Type	Description
AC_SERVER_LOGICAL_NAME	List with a single string	Logical name of the server. Use on the root object only
AC_OBJECT_VERSION_NAME	List with a single string	Version name of the object
AC_OBJECT_COMMENT	List with a single string	User comment on the object
AC_OBJECT_SCHEDULE_START _TIME	List with a single unsigned int	Time in UTC of the request that generated this object
AC_OBJECT_TEMPORARY_STATUS	List with a single Boolean value	A flag to indicate a temporary object
AC_OBJECT_CURRENT_ROI_PAGE _NUMBER	List of properties	Page number information about requests that involve the ROV. Only ROV objects have this property. The last property in the list contains the current page number
AC_OBJECT_CURRENT_ROI_SIZE	List of properties	Size information about requests that involve the ROV. Only ROV objects have this property. The last property in the list contains the current size
AC_OBJECT_NUMBER_OF_PAGES	List with a single unsigned int	The number of pages in the object


Example

Given the path to a folder in the Report Encyclopedia, this example calls GetTree to retrieve the properties associated with the directory and report items it contains.

void ListTree(RWCollectableString fromDirectory)

{

  AcPersistentObject::AcOperationStatus status;

  AcPersistentObject obj(*m_connection,

                         (fromDirectory.length() ? fromDirectory

                          : (RWCollectableString)"/"),

                         AC_VERSION_LATEST, 0,

                         "",

                         status);

  AcProperty tree = obj.GetTree( 0, status);

  if (!status) List(tree);

}


AcPersistentObject::GetType

Example

Retrieves the object's classification.

Syntax

RwCollectableString GetType(AcOperationStatus& operation_status) const

Description

GetType retrieves the current object's type, represented by one of the following strings:

Enumeration constant	Type	Comment
AC_OBJECT_TYPE_DIRECTORY	"Directory"	Path of a report item
AC_OBJECT_TYPE_ROV	"ROV"	Parameter value
AC_OBJECT_TYPE_ROD	"ROD"	Design
AC_OBJECT_TYPE_ROL	"ROL"	Libraries
AC_OBJECT_TYPE_ROX	"ROX"	Executable
AC_OBJECT_TYPE_ROI	"ROI"	Report document
AC_OBJECT_TYPE_BASIC	"Basic"	Basic source code document
AC_OBJECT_TYPE_ROW	"ROW"	Web documents
AC_OBJECT_TYPE_ROP	"ROP"	Report parameters
AC_OBJECT_TYPE_HTML	"HTML"	Hypertext documents
AC_OBJECT_TYPE_BITMAP	"Bitmap"	Bitmaps


Example

This example code sends the ID and names of report items in the Eastern Region folder to standard output, using GetType to ensure the directory is valid.

RWCollectableString directoryName = "/Eastern Region";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj( *m_connection, directoryName,

  AC_VERSION_LATEST, 0, "", status);

RWOrdered objects = obj.GetContainedObjects(status);

cout << "Number of objects:" <<  objects.entries() << endl;

RWOrderedIterator   iterator(objects);

AcPersistentObject* object;

cout << "Directory Name: " << directoryName << endl;

RWCollectableString type = obj.GetType(status);

if (type != AC_OBJECT_TYPE_DIRECTORY) {

  cout << "Not a Directory; Type: " << type << endl;

  }

else {

  while (object = (AcPersistentObject*)iterator()) {

    cout << endl << "Object Name: " << object->GetName(status)

      << " Type: " << object->GetType(status) << " Version: "

      << object->GetVersionNumber(status) << endl << "   ID: "

      << object->GetID(status) << endl;

    }

  }


AcPersistentObject::GetUserNameEventTypes

Returns a list of the event types that the specified user can observe on this object.

Syntax

RWOrdered GetUserNameEventTypes
(const RwCollectableString& user_name,
AcOperationStatus& operation_status) const

user_name

The name of the user who can observe the events.

Description

This function retrieves a list of the types of events that the specified user can observe on this object. The only event type is AC_MESSAGE_OPERATION_STATUS, a macro for "__AC_MESSAGE_OPERATION_STATUS". You must specifically delete the list when you no longer need it.


AcPersistentObject::GetUserNamePrivilegeTypes

Example

Retrieves the user's privileges on this object.

Syntax

RWOrdered GetUserNamePrivilegeTypes
(const RwCollectableString& user_name,
AcOperationStatus& operation_status) const

user_name

The name of the user to get privileges for.

Description

Each persistent object maintains an access list that defines which users have access and what their privileges are. This function returns the list of privileges assigned to a specific user. Delete the list of privileges when you no longer need it.

The following table lists the string values that describe privileges:

Macro	string
AC_PRIVILEGE_TYPE_READ	"Read"
AC_PRIVILEGE_TYPE_WRITE	"Write"
AC_PRIVILEGE_TYPE_EXECUTE	"Execute"
AC_PRIVILEGE_TYPE_DELETE	"Delete"
AC_PRIVILEGE_TYPE_GRANT	"Grant"
AC_PRIVILEGE_TYPE_READ_PROPERTIES	"Read Properties"


Example

This example shows GetUserNamePrivilegeTypes returning the list of privileges assigned to the user named "William" for all versions of the persistent object named forecast.rox. An iterator sends the list of privileges to standard output.

RWCollectableString objectName = "/Eastern Region/forecast.rox";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  RWOrdered privileges =

    object>GetUserNamePrivilegeTypes("William", status);

  RWOrderedIterator privilegeIterator(privileges);

  RWCollectableString* privilege;

  while (privilege = (RWCollectableString*)privilegeIterator()) {

    cout << "\tPrivileges : " << *privilege << endl;

  }

}


AcPersistentObject::GetVersionNumber

See also

Access the version number of the report represented by this object.

Syntax

unsigned long
GetVersionNumber(AcOperationStatus& operation_status) const

Return value

Returns the version number of this object or 0 if there is an error.


See also

AcPersistentObject::GetType


AcPersistentObject::GetVersion

See also

Retrieves a particular version of a report item.

Syntax

AcPersistentObject GetVersion(unsigned long version_number,
AcOperationStatus& operation_status) const

version_number

The version number of the object to be retrieved.

Description

Returns the specified version of this report object as an AcPersistentObject. When a report item is modified, a new version is created automatically if the object has dependents. If the object has no dependents, the modifier must decide whether or not the object is versioned when the report item write access is closed. By having access to one version of a report item, you can access all of the other versions by going up and down the next and previous version pointers of the object.


See also

AcPersistentObject::GetVersions


AcPersistentObject::GetVersions

Example   See also

Returns the versions for this object, a list of AcPersistentObject objects.

Syntax

RWOrdered GetVersions(AcOperationStatus& operation_status) const

Description

This function retrieves a list of persistent objects that represent all versions of a particular object. Delete the contents of the list when you no longer need it.


Example

This example shows GetVersions returning a list of persistent objects representing all versions of the report forecast.roi in the Eastern Region folder. Using GetVersionNumber, the iterator function sends the version number of each version to the standard output.

RWCollectableString objectName = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, objectName,

  AC_VERSION_LATEST, 0, "", status);

cout << "Object Name: " << objectName << endl;

RWOrdered objects = obj.GetVersions(status);

RWOrderedIterator iterator(objects);

AcPersistentObject* object;

while (object = (AcPersistentObject*)iterator()) {

  cout << "Object Version: " << object->GetVersionNumber(status) << endl;

}


See also

AcPersistentObject::GetVersion


AcPersistentObject::Move

Moves this object to the specified object name.

Syntax

AcOperationStatus Move( const RwCollectableString& object_name,
RWBoolean all_versions = FALSE)

object_name

The full name of the destination file (the hierarchical path, name, and extension) where the object is moved.

all_versions

If TRUE, all versions of the report item corresponding to this object are moved. If FALSE, just the persistent object corresponding to the object ID of this object and the objects it contains are moved.

Description

This function either changes the directory of this report, or it increments the version of this report. If the new name of the object resolves to a directory, the function moves one or more objects into the directory. If another object or set of objects already exists with the same full name and they do not resolve to a directory, the function creates a new version of a report item.

If a report item is moved to a directory path that does not exist, the function fails.

When you move a report item from one directory to another, the Report Server removes it from the source directory and adds it to the destination directory.


AcPersistentObject::Read

Example

Reads an object from this persistent object into a buffer.

Syntax

AcOperationStatus Read(
unsigned long 	position,
unsigned char* 	buffer,
unsigned long 	num_bytes_to_read,
unsigned long& 	num_bytes_read,
RWBoolean 	high_performance_flag=FALSE) const

position

The position at which to start reading. Zero specifies the beginning of the file. A nonzero value less than the file size specifies an offset from the beginning of the file. A position equal to the size of the file specifies the end of the file.

buffer

The buffer that holds the bytes read. The caller must create a buffer the size of the maximum number of bytes to be read.

num_bytes_to_read

The maximum number of bytes to read.

num_bytes_read

Returns the number of bytes actually read.

high_performance_flag

If set to TRUE, the data from the read is sent back via sockets. The disadvantage of using this flag is that you get less information if an error occurs during the read.

Description

Reads up to the specified number of bytes from the object. The read starts at the position specified.

To run the example of AcPersistentObject::Read in egclient, enter these arguments for the source and destination files:

C:\API Examples>egclientD -CreportObject -T7 -1"/Eastern Region/forecast.rox" -2C:\Temp\forecast.rox -Mhaleakala -UAdministrator

Enclose the Report Encyclopedia path in quotes when the folder name is more than one word.


Example

The following example shows how to read the report called forecast.roi from the Report Encyclopedia and store it in a destination file on the local drive. For more information, see the egclient Read example in the examples directory of the Report Server API.

RWCollectableString destFile = "D:\\Actuate\\Devwb\\forecast.roi";

RWCollectableString sourceFile = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, sourceFile, AC_VERSION_LATEST,

0, "", status);

if (status != AcPersistentObject::AC_OK) {

cerr << "Could not \"open\" object." << endl;

return 0;

}

RWFile  outputFile(destFile,0);

while ((status = obj.SetReadLock()) != AcPersistentObject::AC_OK) ;

unsigned long l_bufferLength = 1024;

unsigned char* l_buffer = new unsigned char[l_bufferLength];

unsigned long l_offset = 0; int l_maxChunks = -1; l_maxChunks = 10024;

int l_done = 0;

for (int l_current = 0;

l_maxChunks < 0 || l_current < l_maxChunks; l_current++) {

unsigned long l_read = 0;

obj.Read(l_offset, l_buffer, l_bufferLength, l_read);

// write buffer from read block

outputFile.Write(l_buffer, l_read);

l_offset += l_read;

if (l_read == 0) {

l_done = 1;

break;

}

}

obj.UnsetReadLock();


AcPersistentObject::ReadToLocalFile

Reads a specified stream in this object into a local file.

Syntax

void ReadToLocalFile(const RWCollectableString& elementName,
const RWCollectableString& localFileName,
AcOperationStatus& operationStatus)

element_name

The name of the stream.

local_file_name

The full-qualified local file name where the element is written.

Description

Reads from the object stream specified by element_name and writes it to a local file. If you do not explicitly set the read lock on the object, ReadToLocalFile sets it for you.

To protect data integrity when you read from an object repeatedly:

1	Set a readlock on the object using SetReadLock.

2	Do the reads.

3	Unset the read lock, using UnSetReadLock.

For more information, see the egclient reportObject 8 example in the examples directory of the Report Server API.


AcPersistentObject::SetDefaultPrinterName

See also

Sets the default printer for this object to the specified printer.

Syntax

AcOperationStatus SetDefaultPrinterName(const RwCollectableString& printer_name)

printer_name

The name of the printer to be the default printer for this object.


See also

AcPersistentObject::GetDefaultPrinterName


AcPersistentObject::SetDevelopmentStatus

Determines whether an object is a development or released version.

Syntax

AcOperationStatus SetDevelopmentStatus(RWBoolean development_status)

development_status

A TRUE or FALSE flag indicating the development status.

Description

Set to TRUE to indicate that this object is a development version. Set to FALSE to indicate that the object is a released version.


AcPersistentObject::SetOwner

Changes the owner of this object.

Syntax

AcOperationStatus SetOwner(const RwCollectableString& new_owner)

new_owner

The user name of the new owner of the object.

Description

The default owner of an item is the item's creator. Initially, only the owner and administrator can change the owner of an item. The owner can grant privileges on the item.


AcPersistentObject::SetPrinterOptionDefaults

See also

Establishes default settings on a printer.

Syntax

AcOperationStatus SetPrinterOptionDefaults(
const RwCollectableString&	 printer_name,
const RWOrdered&	 option_defaults,
RWBoolean 	default_printer_flag = FALSE)

printer_name

The name of a printer associated with this persistent object.

option_defaults

The parameter that describes the options and attributes of the specified printer, passed as a property list.

Description

This function takes a single-valued list (such as RWBoolean TRUE or an integer) where the first value of the list to the default option.

Use the following table to construct a property list to use as the option_defaults argument:

Option	Property name	Value type
Printer Model - Unix Only	AC_PRINTER_ATTRIBUTE_MODEL	String List (1)
Printer Brand Name - Unix Only	AC_PRINTER_ATTRIBUTE_ DESCRIPTION	String
Location	AC_PRINTER_ATRRIBUTE_LOCATION	String
Orientation	AC_PRINTER_OPTION_ORIENTATION	String List: LANDSCAPE, PORTRAIT
Print to File	AC_PRINTER_OPTION_PRINT_TO_FILE	String
Paper Length	AC_PRINTER_OPTION_PAPER_LENGTH	Integer
Page Range	AC_PRINTER_OPTION_PAGE_RANGE	Integer
Paper Width	AC_PRINTER_OPTION_PAPER_WIDTH	Integer
Form Name	AC_PRINTER_OPTION_FORMNAME	Integer. For more information, see AC_PRINTER_OPTION_FORMNAME
Scale	AC_PRINTER_OPTION_SCALE	Integer
Resolution	AC_PRINTER_OPTION_RESOLUTION	String List
Copies	AC_PRINTER_OPTION_COPIES	Integer
Page Size	AC_PRINTER_OPTION_PAGE_SIZE	String List
Paper Tray	AC_PRINTER_OPTION_PAPER_TRAY	String List
Color	AC_PRINTER_OPTION_COLOR	Boolean
Duplex	AC_PRINTER_OPTION_DUPLEX	String List SIMPLEX, HORIZONTAL, VERTICAL
Collate	AC_PRINTER_OPTION_COLLATE	Boolean
(1) Model names returned by XPrinter, a Bristol Technology printer driver for UNIX.

default_printer_flag

When set to TRUE, designates the specified printer as the default printer for this object.

Description

Sets the default parameters for the specified printer for this object. Typical options are printer type, model, and capabilities. Printer properties can be set at the following levels:

•	System

•	User

•	Object

•	Request

Properties set at the request level override properties set at lower (object, user, and system) levels, and properties set at the object or user level override properties set at a lower level. The function sets the object level options.


See also

AcPersistentObject::GetPrinterOptionDefaults


AcPersistentObject::SetReadLock

See also

Locks the current object so that it cannot be changed during a read operation.

Syntax

AcOperationStatus SetReadLock()

Description

Sets a read lock on the persistent object.

Note

To prevent other processes from creating a new version of the object while your application reads it, you must explicitly set a read lock, read the object, and then explicitly unset the read lock with UnsetReadLock.


See also

AcPersistentObject::ReadToLocalFile

AcPersistentObject::UnsetReadLock

AcPersistentObject::Read


AcPersistentObject::SetWriteLock

See also

Locks this object to ensure its integrity during a write operation.

Syntax

AcOperationStatus SetWriteLock()

Description

Sets a write lock on the persistent object. To prevent other processes from writing to an object while your application uses it, use SetWriteLock. The write lock is removed when UnsetWriteLock is called or when this client object is destroyed. Unset the write lock, using UnsetWriteLock.


See also

AcPersistentObject::Write


AcPersistentObject::UnsetReadLock

See also

Unsets the read lock on the persistent object.

Syntax

AcOperationStatus UnsetReadLock()

Description

Unsets the read lock on the persistent object. To protect multiple reads from the same object, you must explicitly set a read lock, using SetReadLock, do the multiple reads, and then explicitly unset the read lock, using UnsetReadLock.


See also

AcPersistentObject::SetReadLock

AcPersistentObject::ReadToLocalFile

AcPersistentObject::Read


AcPersistentObject::UnsetWriteLock

See also

Unsets the write lock on the persistent object.

Syntax

AcOperationStatus UnsetWriteLock(RWBoolean version=FALSE)

version

If TRUE, a new version of the object is created when the lock is removed.

Description

When you unset a write lock, you cannot modify the contents of an object; you can only replace the object.


See also

AcPersistentObject::SetWriteLock

AcPersistentObject::Write


AcPersistentObject::Write

Example

Writes data to an object.

Syntax

AcOperationStatus Write(unsigned long position,
const unsigned char* 	bytes,
unsigned long 	num_bytes_to_write,
unsigned long& 	num_bytes_written)

AcOperationStatus Write(unsigned long position,
const RWCollectableString& 	bytes,
unsigned long& 	num_bytes_written);

position

The address at which to start writing. Zero specifies the beginning of the file. A nonzero value less than the file size specifies an offset from the beginning of the file. A position equal to the size of the file specifies the end of the file.

bytes

The bytes to be written.

num_bytes_to _write

The maximum number of bytes to write.

num_bytes_written

Returns the number of bytes actually written.

Description

Writes either a datastream or the specified number of bytes to the object's contents. Given the length of the bytes to write, use the first form of this function. Use the second form to enter the bytes as a stream. If no write lock has been set when this function is called, an implicit write lock is set and unset, and the a new version is created.


Example

This example shows how to open a local file called forecast.roi and write it to the Eastern Region folder of the Report Encyclopedia.

RWCollectableString sourceFile = "D:\\Actuate\\Devwb\\forecast.roi";

RWCollectableString destFile = "/Eastern Region/forecast.roi";

AcPersistentObject::AcOperationStatus status;

AcPersistentObject obj(*m_connection, destFile, AC_VERSION_LATEST,

0,"ROI", status);

RWFile file(sourceFile); file.SeekToEnd(); long size = file.CurOffset();

file.SeekToBegin(); static char buffer[1000000];

file.Read(buffer, size);

RWCollectableString contents(buffer, size);

status = AcPersistentObject::AC_ERROR;

while (status != AcPersistentObject::AC_OK) {

status = obj.SetWriteLock();

}

unsigned long numBytesWritten;

status = obj.Write(0, contents, numBytesWritten);

status = obj.UnsetWriteLock( TRUE);


AcPrintObject

Example   See also   Member functions of AcPrintObject

Creates a message that requests printing the accompanying report item to a file or a printer.

Description

Set the ROI to be printed using SetInputObject. If no dependency is set for the ROI, specify the ROX using SetExecutableObject. If you want to print to a file, specify a file in the file system, not the Report Encyclopedia, using the printer request option, AC_PRINTER_OPTION_PRINT_TO_FILE.

Public member functions

Member function	Description
GetRequestID	Returns the ID of the request to print this object.
SetPrinterName	Establishes the printer where the report is to be printed.
SetInputObjectID	Specifies, by ID, the input object (currently an ROI only) that is the target of the print request.
SetInputObjectName	Specifies, by name, the input object (currently an ROI only) that is the target of the print request.
SetExecutableName	Specifies, by name, the executable (ROX) corresponding to this ROI to be printed.
SetExecutableID	Specifies, by ID, the executable (ROX) corresponding to this ROI to be printed.
SetRequestOptions	Sets options to be used with this request to print an object.
SetSchedule	Sets the repeat schedule of this request to print.


Example

This example shows how to print a report called my.rox to a postscript file.

AcPrintObject req;

req.SetInputObjectName("/ServerFolder/my.roi");

req.SetExecutableObjectName("/ServerFolder/my.rox");

AcProperty fileToPrintTo;

fileToPrintTo.SetName(AC_PRINTER_OPTION_PRINT_TO_FILE);

fileToPrintTo.SetStringValue("/UnixOrNTDirectory/file.ps");

RWOrdered printOptionsValues;

printOptionsValues.append(&fileToPrintTo);

AcProperty printOptions;

printOptions.SetName(AC_PRINTER_REQUEST_OPTIONS);

printOptions.SetPropertyListValue(printOptionsValues);

RWOrdered reqOptions;

reqOptions.append(&printOptions);

req.SetRequestOptions(reqOptions);

\\Send the request...


See also

AcPrintObject::SetRequestOptions


Member functions of AcPrintObject

AcPrintObject::GetRequestID

AcPrintObject::SetPrinterName

AcPrintObject::SetInputObjectID

AcPrintObject::SetInputObjectName

AcPrintObject::SetExecutableName

AcPrintObject::SetExecutableID

AcPrintObject::SetRequestOptions

AcPrintObject::SetSchedule


AcPrintObject::GetRequestID

Returns the ID of the request to print this object.

Syntax

RWCollectableString GetRequestID() const


AcPrintObject::SetPrinterName

Example

Sets the name of the printer where the report is to be printed. If requested, the print server prints to the printer.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer. Strings in the source code specifying the printer take double backslashes. The first backslash is the escape character. For more information, see Referring to files--Windows environment.


Example

In the Windows environment, name the printer this way:

AcPrintObject PO;

PO.SetPrinterName("\\\\Machine\\HP LASERJET IIP");


AcPrintObject::SetInputObjectID

See also

Specifies, by ID, the input object (currently an ROI only) that is the target of the print request.

Syntax

void SetInputObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object. The global unique ID of a persistent object is independent of its name and location.

Description

There are two ways to specify the input object, an ROI, to be printed: by ID or name. Either the name or the ID of the object should be specified, but not both. The last specified of the two is the one used when a request is sent.


See also

AcPrintObject::SetInputObjectName


AcPrintObject::SetInputObjectName

Specifies, by name, the input object (currently an ROI only) that is the target of the print request.

Syntax

void SetInputObjectName(const RWCollectableString& object_name,
AcVersionType version_type=AC_VERSION_LATEST,
unsigned long version_number=1)

object_name

The user-defined name of the object. This is the full name of the object, including the hierarchical path of the object. For more information, see Referring to files--Windows environment.

version_type

A classification of this iteration of a report object. By default, this function uses the latest version of the object, but you can specify a certain version number, the latest development version, or the latest released version.

version_number

The specific version number. Use this parameter when you set the version type to AC_VERSION_SPECIFIC to request a specific version number of the object.

Description

There are two ways to specify the input object, an ROI, to be printed: by ID or name. Either the name or the ID of the object should be specified, not both. The last specified of the two is the one used when a request is sent.

version_type is of AcVersionType, which defines the following enumerated constants. If you specify the object by name, then you can specify the version of the object.

The following table lists the AcVersionType values:

Value	Meaning
AC_VERSION_LATEST	If specified, the latest version of the object is always used.
AC_VERSION_LATEST_DEVELOPMENT	If specified, the latest development version of the object is always used.
AC_VERSION_LATEST_RELEASED	If specified, the latest released version of the object is  always used.
AC_VERSION_OLDEST	If specified, the oldest version of the object is always used.
AC_VERSION_SPECIFIC	If specified, the specific version number is used.


AcPrintObject::SetExecutableName

Specifies the name of the report executable to print.

Syntax

void SetExecutableName(const RWCollectableString& object_name,
AcVersionType version_type=AC_VERSION_LATEST,
unsigned long version_number=1)

object_name

The user defined name of the object. This is the full name of the object, including the hierarchical path of the object.

version_type

A classification of this iteration of a report object. By default, the latest version of the object is used.

version_number

A number that augments a file name to guarantee the uniqueness of file names for all versions of a report object. Pass a zero unless you use the parameter AC_VERSION_SPECIFIC for the version_type. Passing a nonzero number specifies the specific version number of the object. Use AC_VERSION_-LATEST_DEVELOPMENT and AC_VERSION_LATEST_RELEASED to specify objects stamped as such, regardless of the version number.

Description

There are two ways to specify the executable of the object to be printed: by ID or name. Specify either the name or the ID, not both. The last specified of the two is the one used when a request is sent. Some report files depend on the existence of others. An ROI and ROV depend on an ROX. If no executable object is specified, either this object doesn't require it, or the object this object is dependent on is used automatically, if the object is of the correct type (an ROX).

version_type is an AcVersionType, which defines the following enumerated constants:

Value	Meaning
AC_VERSION_LATEST	The most recent version of the object, which is the default version type.
AC_VERSION_LATEST_ DEVELOPMENT	The version that has been flagged by a call to SetDevelopmentStatus as a development version.
AC_VERSION_LATEST_ RELEASED	The version that has been flagged by a call to SetDevelopmentStatus as a released version.
AC_VERSION_OLDEST	The initial version of the object.
AC_VERSION_SPECIFIC	A particular version number of the object is specified with the next parameter, version_number.


AcPrintObject::SetExecutableID

Specifies, by ID, the executable (ROX) corresponding to this ROI to be printed.

Syntax

void SetExecutableID(const RWCollectableString& object_id)

object_id

The global unique ID of the object. The global unique ID of a persistent object is independent of its name and location.

Description

There are two ways to specify the executable of the object to be printed: by ID or name. Specify either the name or the ID of the object, not both. The last specified of the two is the one used when a request is sent. Some report files depend on the existence of others. An ROI and ROV depend on an ROX. If no executable object is specified, either this object doesn't require it, or the object this object is dependent on is used automatically, if the object is of the correct type (an ROX).


AcPrintObject::SetRequestOptions

See also

Sets options to be used with this request to print an object.

Syntax

void SetRequestOptions(const RWOrdered& request_options)

request_options

The request options: a list of properties.

Description

SetRequestOptions sets the options to use to print an object (ROI), such as access privileges.

The following table describes the parameter, showing the two types of top level properties within the nested list and the request level list that each of the types can contain:

Top level property	Request level property list
property name = AC_REQUEST_OUTPUT_ OBJECT_PRIVILEGES
property value = property list	name = Role ID or User ID
	semantic type = AC_SEMANTIC_ TYPE_ROLE or AC_SEMANTIC_ TYPE_USER
	value = a string list specifying read, write, and other privileges. For more information, see AcAddPrivilegeToUser::SetPrivilegeType
property name = AC_PRINTER_REQUEST_ OPTIONS
property value = property list	name = one of the printer option property names. For more information, see AcGetPrinterInformation::GetPrinterOptions
	value = one of the printer option property values.
There are two top level properties:

•	AC_REQUEST_OUTPUT_OBJECT_PRIVILEGES specifies user or role privileges for the output report when requesting report execution. The value of the top level property is a property list. The name of each property in the list is a role ID or user ID, depending on the semantic type of the property. The semantic type of the property must be either AC_SEMANTIC_TYPE_ROLE or AC_SEMANTIC_TYPE_USER. The value of each property is an ordered list of strings specifying all the privilege relationships between the user or role named in the property and the generated report.

•	AC_PRINTER_REQUEST_OPTIONS specifies settable printer options. The value of the top level property is a property list. The name of each property in the list is a printer option name and the value is the option setting.


See also

AcAddPrivilegeToUser::SetPrivilegeType

AcGetPrinterInformation::GetPrinterOptions

AcProperty::GetSemanticType

AcExecuteAndPrintObject::SetRequestOptions


AcPrintObject::SetSchedule

See also

Sets the repeat schedule of this request to print.

Syntax

void SetSchedule(const RWOrdered& schedule)

schedule

The repeat schedule. This is a list of AcSchedule objects that specify the schedule of this request.


See also

AcExecuteAndPrintObject::SetSchedule

AcSchedule


AcProperty

Example   See also   Member functions of AcProperty

Represents property values in messages.

Description

AcProperty objects represent property values and are used as input parameters and return values in messages. A property is information, one piece of information or a list of characteristics of a report item or printer settings. For example, the file name, creator, location, creation date and so on are report items properties. The items in the Requests folders have properties associated with their completion and schedule, for example.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetBooleanValue	Returns a TRUE or FALSE value for this property.
GetByteArrayValue	Returns a byte array value for this property.
GetDataType	Returns the data type of the property.
GetIntegerValue	Returns the long integer value of this property.
GetName	Returns the name of the property.
GetPropertyListValue	Returns a list of properties for this property.
GetRealValue	Returns a value, a real for this property.
GetSemanticType	Returns the semantic type for this property.
GetStringList	Returns a string list value for this property.
GetStringValue	Returns a string value for this property.
GetUnsignedIntegerValue	Returns an unsigned int value for this property.
SetBooleanValue	Establishes an RWBoolean value, TRUE or FALSE, for this property.
SetByteArrayValue	Establishes a byte array value for this property.
SetDoubleValue	Establishes a double value for this property.
SetIntegerValue	Establishes an integer value for this property.
SetName	Identifies the property by name.
SetPropertyListValue	Establishes a property list value for this property.
SetSemanticType	Establishes the semantic type of the value for this property.
SetStringValue	Establishes a string value for this property.
SetStringListValue	Establishes a string list value for this property.
SetUnsignedIntegerValue	Establishes an unsigned int value for this property.


Example

The following example shows how to retrieve and display a property list, the administrator's preferences.

AcGetUserPreferences getUserPreferences;

getUserPreferences.SetUserName("Administrator");

m_sendStatus =m_connection->SendRequest(getUserPreferences, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

RWOrdered preferences = getUserPreferences.GetUserPreferences();

RWOrderedIterator l_iter((RWOrdered&) preferences);

AcProperty* property;

while (property = RW_SAFE_CAST(l_iter(), AcProperty, __ACPROPERTY)) {

cout <<  property->GetName() << ". . . . . . . . ."

<< property->GetStringValue() << endl;

}

preferences.clearAndDestroy();

}

The output from this example might look like this:

Connected To Server With  Status  : 0
__AC_USER_EMAIL_ID. . . . . . . . .
__AC_USER_EMAIL_FORM. . . . . . . . .
__AC_USER_HOME_FOLDER. . . . . . . . .
__AC_USER_NOTIFICATION_TYPE. . . . . . . . .
__AC_USER_SERVER_NOTICE. . . . . . . . .Yes
__AC_USER_FIRST_VISIBLE_FOLDER. . . . . . . . .1
__AC_USER_SELECTED_ITEMS. . . . . . . . .
__AC_USER_EXPANDED_FOLDERS. . . . . . . . .
__AC_USER_MAX_PRIORITY. . . . . . . . .
__AC_USER_DEFAULT_OBJECT_PRIVILEGES. . . . . . . . .
__AC_USER_MAX_COMPLETED. . . . . . . . .20


See also

AcGetUserPreferences

AcPersistentObject::GetTree


Member functions of AcProperty

AcProperty::GetBooleanValue

AcProperty::GetByteArrayValue

AcProperty::GetDataType

AcProperty::GetIntegerValue

AcProperty::GetName

AcProperty::GetPropertyListValue

AcProperty::GetRealValue

AcProperty::GetSemanticType

AcProperty::GetStringList

AcProperty::GetStringValue

AcProperty::GetUnsignedIntegerValue

AcProperty::SetBooleanValue

AcProperty::SetByteArrayValue

AcProperty::SetDoubleValue

AcProperty::SetIntegerValue

AcProperty::SetName

AcProperty::SetPropertyListValue

AcProperty::SetSemanticType

AcProperty::SetStringValue

AcProperty::SetStringListValue

AcProperty::SetUnsignedIntegerValue


AcProperty::GetBooleanValue

Returns the value, TRUE or FALSE, of the element.

Syntax

RWBoolean GetBooleanValue() const

Return value

Returns the Boolean value of this element. If the data type of this element is not Boolean, the return value contains FALSE.


AcProperty::GetByteArrayValue

Returns the value, a byte array, of the element.

Syntax

RWCollectableString GetByteArrayValue() const

Description

If the data type of this element is not a byte array, the return value contains a NULL.


AcProperty::GetDataType

Returns the data type of the element.

Syntax

AcDataType GetDataType() const

Description

AcDataType is a nested enumerated type that defines element data types. The types are:

•	AcProperty::AC_NO_TYPE

•	AcProperty::AC_BOOLEAN

•	AcProperty::AC_INTEGER

•	AcProperty::AC_UNSIGNED_INTEGER

•	AcProperty::AC_REAL

•	AcProperty::AC_STRING

•	AcProperty::AC_BYTE_ARRAY

•	AcProperty::AC_STRING_LIST

•	AcProperty::AC_PROPERTY_LIST


AcProperty::GetIntegerValue

Returns the long integer value of the element.

Syntax

long GetIntegerValue() const

Return value

If the data type of this element is not an integer, the return value contains LONG_MIN.


AcProperty::GetName

Returns the name of the element.

Syntax

RWCollectableString GetName() const


AcProperty::GetPropertyListValue

Returns the property list value of the element.

Syntax

RWOrdered GetPropertyListValue() const

Description

Returns the property list as an RWOrdered list. Delete the contents of the ordered collection returned by this function.


AcProperty::GetRealValue

Returns the value, a real, of the element.

Syntax

double GetRealValue() const

Return value

If the data type of this element is not real, the return value contains DBL_MAX.


AcProperty::GetSemanticType

Returns the semantic type of the element.

Syntax

RWCollectableString GetSemanticType() const

Description

This function returns information you can use to determine what the element actually contains. For example, the data type might be an AcProperty::STRING, but the semantic type might be AC_SEMANTIC_TYPE_OBJECT_ID. The property semantic types are:

Type	Definition
AC_SEMANTIC_TYPE_OBJECT_ID	The property contains an object ID for its value.
AC_SEMANTIC_TYPE_OBJECT_NAME	The property contains an object name for its value.
AC_SEMANTIC_TYPE_DAY_NUMBER	The property contains a day number (0-6 for Sunday through Saturday, 7 for all weekdays) for its value.
AC_SEMANTIC_TYPE_ROLE	The value of the property pertains to a role.
AC_SEMANTIC_TYPE_SECONDS	The unit of the value of the property is seconds.
AC_SEMANTIC_TYPE_USER	The value of the property pertains to a user.


AcProperty::GetStringList

Returns the string list value of the element.

Syntax

RWOrdered GetStringList() const

Description

Returns the string list of this element. If the data type of this element is not a string list, the return value contains an empty ordered list. The caller is responsible for deleting the contents of the ordered collection returned by this function.


AcProperty::GetStringValue

Returns the string value of the element.

Syntax

RWCollectableString GetStringValue() const

Description

If the data type of this element is not a string value, the return value contains a NULL String.


AcProperty::GetUnsignedIntegerValue

Returns the unsigned interger value of the element.

Syntax

unsigned long GetUnsignedIntegerValue() const

Return value

Returns the unsigned integer value of this element. If the data type of this element is not an unsigned integer, the return value contains ULONG_MAX.


AcProperty::SetBooleanValue

Sets the value of this element to TRUE or FALSE.

Syntax

void SetBooleanValue(RWBoolean boolean_value)

boolean_value

A RWBoolean value, TRUE or FALSE.


AcProperty::SetByteArrayValue

Sets the value of this element to an array of bytes.

Syntax

void SetByteArrayValue(const RWCollectableString& bytes_value)

bytes_value

An array of bytes value.


AcProperty::SetDoubleValue

Sets the value of this element to a double.

Syntax

void SetDoubleValue(double real_value)

real_value

A double precision real value.


AcProperty::SetIntegerValue

Sets the value of this element to a long.

Syntax

void SetIntegerValue(long integer_value)

integer_value

A long integer value.


AcProperty::SetName

See also

Specifies the name of the property on a per message basis.

Syntax

void SetName(const RWCollectableString& name)

name

The name of the element.


See also

AcProperty


AcProperty::SetPropertyListValue

Sets the value of this element to a list of properties.

Syntax

void SetPropertyListValue(const RWOrdered& property_list)

property_list

Property values lists may be public or private.

For example, here are two properties from the public list

"__AC_OBJECT_ VERSION_NAME"	Has one property with the version name of the object.
"__AC_OBJECT_ SCHEDULE_START_TIME"	Has one property with an unsigned integer value that specifies the time in UTC of the request that generated this object.
.

And here are a few properties from the private property list:

Type	The type of object, either a directory or report items. All objects must have this property.
User ID of Owner	The ID of the user that currently owns the object. All objects must have this property.
Date/Time Created	The date and time the object was created. All objects must have this property.


AcProperty::SetSemanticType

Example

Establishes the semantic type for managing information about properties.

Syntax

void SetSemanticType(const RWCollectableString& semantic_type)

semantic_type

The semantic type of the element.

Description

This function sets information you can use to determine what the element actually contains. For example, the data type might by an AcProperty::STRING, but the semantic type might be AC_SEMANTIC_TYPE_OBJECT_ID. The property semantic types are:

AC_SEMANTIC_TYPE_OBJECT_ID

AC_SEMANTIC_TYPE_OBJECT_NAME

AC_SEMANTIC_TYPE_DAY_NUMBER

AC_SEMANTIC_TYPE_SECONDS

AC_SEMANTIC_TYPE_ROLE

AC_SEMANTIC_TYPE_USER


Example

This example shows setting the semantic type for a user, William.

AcProperty property;

property.SetName(idWilliam);

property.SetSemanticType(AC_SEMANTIC_TYPE_USER);

property.SetStringListValue(list);

list.clearAndDestroy();

list.append(new AcProperty(property));


AcProperty::SetStringValue

Sets the value of this element to a string.

Syntax

void SetStringValue(const RWCollectableString& string_value)

string_value

A string value.


AcProperty::SetStringListValue

Sets the value of this element to a list of strings.

Syntax

void SetStringListValue(const RWOrdered& string_list)

string_list

A list of string values.


AcProperty::SetUnsignedIntegerValue

Sets the value of this element to an unsigned long.

Syntax

void SetUnsignedIntegerValue(unsigned long unsigned_integer_value)

unsigned_integer_value

An unsigned long integer value.


AcRequest

Member functions of AcRequest

Describes the client's demands to the connection object.

Description

AcRequest represents a message for AcConnection regarding the client requests of the Report Server. Typically, you use an object derived from AcRequest, rather than instantiating it directly. For information on the Report Server system, see Report Encyclopedia events.

Public member functions

Typically, the following public member functions are called indirectly by derived classes of AcRequest. The functions initialize and access AcRequest private data members, such as the location and priority of the request.

Member function	Description
GetBatchDisposition	Returns the batch status of a request that indicates whether or not the request is batched.
GetHostName	Returns the name of the machine where the request will be sent.
GetPriority	Returns the priority of execution of the request as allowed by the privileges of the client.
GetSchedule	Returns the repeat schedule of this request.
GetServername	Returns the name of the server to receive the request.
GetServerType	Returns the type of the server to receive the request.
SetBatchDisposition	Specifies whether or not the request is batched, depending on the availability of operation servers.
SetForcedRequestID	Specifies the identifier for a request that is unique to the server, for this request. If unspecified, the system generates a request ID.
SetHostName	Specifies the name of the machine where this request is to be made.
SetPriority	Specifies the scheduling precedence for running the reports associated with this request.
SetServerName	Specifies the name of the specific server to receive the request being sent.
Protected member functions

Member function	Description
GetInputObjectID	Returns the identifier. The ID is unique for the input object of this request within the server.
GetInputObjectName	Returns the name of the input object, including version information, for this request.
GetOutputObjectID	Returns the ID of the object that is the result of the request.
GetOutPutObjectName	Returns the name of the object that is the result of the request.
SetInputObjectID	Specifies by ID of the input object for executing the request.
SetInputObjectName	Specifies by name of the input object for executing the request.
SetOutputObjectID	Specifies the output object ID for this request.
SetOutputObjectName	Specifies the output object name for this request.
SetSchedule	Sets the repeat schedule of this request.
SetServerType	Specifies the type of server that can receive the request.


Member functions of AcRequest

AcRequest::GetBatchDisposition

AcRequest::GetHostName

AcRequest::GetPriority

AcRequest::GetSchedule

AcRequest::GetServerName

AcRequest::GetServerType

AcRequest::SetBatchDisposition

AcRequest::SetForcedRequestID

AcRequest::SetHostName

AcRequest::SetPriority

AcRequest::SetServerName

AcRequest::GetInputObjectID

AcRequest::GetInputObjectName

AcRequest::GetOutputObjectID

AcRequest::GetOutputObjectName

AcRequest::SetInputObjectID

AcRequest::SetInputObjectName

AcRequest::SetOutputObjectID

AcRequest::SetOutputObjectName

AcRequest::SetSchedule

AcRequest::SetServerType


AcRequest constructors

Example

This class has default and copy constructors and a constructor that creates a copy of the request object with this message.

Syntax

AcRequest(const AcMessage& message)

Description

AcRequest is a base class from which classes, such as AcExecuteAndPrintObject, have been derived to do the real work. The AcRequest default constructor creates an empty AcRequest message object.


Example

The following example indirectly constructs AcRequest when AcPrintObject is constructed. SetExecutableObjectName calls AcRequest::SetInputObjectName to initialize the request.

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcExecuteAndPrintObject eAndp;

eAndp.SetInputObjectName("/Eastern Region/forecast.rox");

eAndp.SetValuesObjectName("/Eastern Region/forecast.rov");

eAndp.SetOutputObjectName("/Eastern Region/forecast.roi",TRUE);

eAndp.SetPrinterName("\\\\lahaina\\HP LASERJET IIP");

m_sendStatus =m_connection->SendRequest(  eAndp, m_timeout);


AcRequest destructor

There are no side effects when an AcRequest object is destroyed.

Syntax

~AcRequest()

If the request was sent but not responded to, the contents are not destroyed, because the AcClientConnection object has a reference to the contents.


AcRequest::GetBatchDisposition

Returns the batch status of a request that indicates whether or not the request is batched.

Syntax

RWBoolean GetBatchDisposition() const

Description

If the request is not a batch request and a suitable server is not available, the request fails and the requesting user is notified. If the request is a batch request, the request server holds it until a suitable server is available. A request might be batched. The request server often batches low-priority requests. For more information, see Batch request.

Return value

TRUE if the request is batched, FALSE otherwise.


AcRequest::GetHostName

Returns the name of the machine to run the request.

Syntax

RWCollectableString GetHostName() const


AcRequest::GetPriority

See also

Returns the priority of execution for the request, as allowed by the privileges of the client.

Syntax

int GetPriority() const

Return value

An integer between 0-1000, which is the limit imposed by the SetPriority member.


See also

AcRequest::SetPriority


AcRequest::GetSchedule

See also

Returns the repeat schedule of this request. Protected.

Syntax

RWOrdered GetSchedule() const

Description

This function gets the repeat schedule for report generation or printing. A schedule can specify that a report run immediately, once at a specified time, on a recurring basis, or on any specified schedule. You can query the repeat scheduling information and report it by user, type of operation, or object operated on.

Return value

A list of AcSchedule objects that specify the schedule of this request.


See also

AcSchedule


AcRequest::GetServerName

Returns the name of the server to receive the request being sent.

Syntax

RWCollectableString GetServerName() const


AcRequest::GetServerType

Returns the type of server to receive the request being sent.

Syntax

RWCollectableString GetServerType() const


AcRequest::SetBatchDisposition

Specifies whether or not the request is batched, depending on the availability of operation servers.

Syntax

void SetBatchDisposition(RWBoolean batch_disposition)

batch_disposition

A boolean that specifies the batch disposition.

Description

SetBatchDisposition passes TRUE or FALSE to specify batching or no batching, respectively, of the request. For example, if no operation servers are running or no operation servers can be started to handle the request, it is batched.


AcRequest::SetForcedRequestID

See also

Specifies an identifier, unique to the server, for this request. If unspecified, the request ID is automatically generated.

Syntax

void SetForcedRequestID(const RWCollectableString &request_id)

request_id

The identifier for the request.

Description

Before calling this function, call AcGetUniqueRequestID::GetRequestID to get a unique ID. Next, specify the request identifier to the server by calling SetForcedRequestID to set the ID to the given value rather than the system-generated one.


See also

AcGetUniqueRequestID::GetRequestID


AcRequest::SetHostName

Specifies the name of the machine where the request is to be made.

Syntax

void SetHostName(const RWCollectableString &host_name)

host_name

A machine name.


AcRequest::SetPriority

Specifies the scheduling precedence for running reports.

Syntax

void SetPriority(int priority)

priority

An integer between 0-1000 with 1000 the highest priority. The priority cannot be set outside the limits defined by the user's privilege.


AcRequest::SetServerName

Specifies the name of the specific server to receive the request being sent.

Syntax

void SetServerName(const RWCollectableString &server_name)

server_name

An operation server name. If the server name is unspecified, the request can use any operation server capable of handling the request.


AcRequest::GetInputObjectID

See also

Returns the identifier, unique within the server, for the input object. Protected.

Syntax

RWCollectableString GetInputObjectID() const

Description

Retrieves the input object ID, for example, the ID of an ROX if the application requests execution or the ID of an ROI if the application requests printing. There are two ways to specify the input object, by calling SetInputID or SetInputName. The last specified of the two is the one used when a request is sent. If you set the input object name, you cannot use this function. For more information, see Input and output objects.

Return value

The input object ID on success, an empty string if the name was set instead of the ID.


See also

AcRequest::GetInputObjectName


AcRequest::GetInputObjectName

See also

Returns the name of the target object and version information. Protected.

Syntax

RWCollectableString GetInputObjectName() const

Return value

The input object name on success, an empty string if the ID was set instead of the name. For more information, see Input and output objects.


See also

AcRequest::SetInputObjectName


AcRequest::GetOutputObjectID

See also

Returns the object ID. Protected.

Syntax

RWCollectableString GetOuputObjectID() const

Description

Returns the ID of the object that is the result of the request. For example, a request to execute an ROX object returns the ID of the resulting ROI.

Return value

The input object name on success, an empty string if the ID was set instead of the name.

Description

This function returns the ID of the object that is the result of the request or an empty string on failure. For more information, see Input and output objects.


See also

AcRequest::SetOutputObjectID


AcRequest::GetOutputObjectName

See also

Returns the name of the object that is the result of the request. Protected.

Syntax

RWCollectableString GetOutputObjectName() const

Description

This function returns the name of the target object, such as the name of the ROI that results from execution of an ROX. The retrieved name includes updated versioning for the object. The function returns an empty string if an ID was set instead of a name. For more information, see Input and output objects.


See also

AcRequest::SetOutputObjectID


AcRequest::SetInputObjectID

Specifies the input object for executing the request, by ID. Protected.

Syntax

void SetInputObjectID(const RWCollectableString& object_id)

object_id

The global unique ID of the object. For more information, see Input and output objects.


AcRequest::SetInputObjectName

See also

Specifies the input object for executing the request, by name. Protected.

Syntax

void SetInputObjectName(const RWCollectableString& object_name)

object_name

The user-defined, fully qualified path name of the object. For more information, see Input and output objects.


See also

AcClientConnection::SetWorkingDirectory


AcRequest::SetOutputObjectID

Specifies the output object ID for this request. Protected.

Syntax

void SetOutputObjectID(const RWCollectableString& object_id, RWBoolean version = FALSE)

object_id

The global unique ID of the object.

version

TRUE to create a new version of the object, FALSE otherwise.

Description

The function identifies the output object for this request, by ID. For example, the function might specify the ID of an ROI as the output file that results from execution of the request.

Requests can specify whether or not to create new versions of an output object. Set version to TRUE to create a unique ID for the new object; FALSE to overwrite an existing object.

If you set version to FALSE and a version the object already exists and has no dependents, it is overwritten. Some report files depend on the existence of others. For example, an ROI and ROV depend on an ROX.

For more information, see Input and output objects.


AcRequest::SetOutputObjectName

See also

Specifies the output object name for this request. Protected.

Syntax

void SetOutputObjectName(const RWCollectableString& object_name, RWBoolean version = FALSE)

object_name

The user-defined, fully qualified path name of the object.

version

TRUE to create a new version of the object, FALSE otherwise.

Description

The function identifies the output object for this request, by name. For example, the function might specify the name of an ROI as the output file that results from execution of the request.

Requests can specify whether or not to create new versions of an output object. Set version to TRUE to create a new object; FALSE to overwrite an existing object.

If you set version to FALSE and a version the object already exists and has no dependents, it is overwritten. Some report files depend on the existence of others. For example, an ROI and ROV depend on an ROX.

For more information, see Input and output objects.


See also

AcClientConnection::SetWorkingDirectory


AcRequest::SetSchedule

See also

Sets the repeat schedule of this request. Protected.

Syntax

void SetSchedule(constRWOrdered& schedule)

schedule

A list of AcSchedule objects that specifies the schedule for executing or printing reports.


See also

AcExecuteAndPrintObject::SetSchedule


AcRequest::SetServerType

Specifies the type of server that can receive this request. Protected.

Syntax

void SetServerType(const RWCollectableString &server_type)

server_type

One of the following strings:

•	"Administration Server"

•	"Factory Server"

•	"Persistent Object Server"

•	"Print Server"

•	"Request Server"


AcSchedule

Example   Member functions of AcSchedule

Encapsulates a schedule that is used to specify when to execute or print a report.

Description

The AcSchedule object can represent a time interval or a set of specific times during a day, week, month, or year.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
AddAbsoluteDate	Specifies a certain date for scheduling rather than recurring dates.
AddAbsoluteTime	Specifies a time for the schedule to execute during the days that have been added to the schedule and adds the time.
AddDayOfMonth	Adds a day of the month to the schedule.
AddDayOfPeriod	Adds a day of the period to the schedule.
AddDayOfWeek	Adds a day of the week to the schedule.
AddDayOfYear	Adds a day of the year to the schedule.
AddMaskDate	Adds a mask date to the schedule that specifies a date is excluded from the schedule.
GetAbsoluteDates	Returns the dates that have been added to this schedule.
GetAbsoluteTimes	Returns the specific time for the schedule to execute during the days that have been added to the schedule.
GetDaysOfMonth	Returns the days of the month for this schedule.
GetDaysOfPeriod	Returns the days of the period for this schedule.
GetDaysOfWeek	Returns the days of the week for this schedule.
GetDaysOfYear	Returns the days of the year for this schedule.
GetDurationInSeconds	Returns the duration of the schedule in seconds.
GetEndDate	Returns the date the schedule terminates.
GetMaskDates	Returns the dates excluded from the schedule.
GetPeriod	Accesses the period associated with this schedule.
GetStartDate	Gets the date the schedule becomes effective.
GetTimeInterval	Returns by reference the time interval specifications for repeating a schedule. The schedule starts at the specified time and is repeated at the intervals until the end of the day.
GetTimeZone	Returns the time zone set for the schedule.
GetTypeOfDayInPeriod	Gets a type of day, Monday through Sunday, in the period for the schedule.
IsNull	Returns TRUE if no schedule settings exist. Returns FALSE if this schedule has at least a start date and either an interval or absolute times specified.
SetDurationInSeconds	Sets how many seconds the repeat schedule request executes.
SetEndDate	Establishes the date the schedule terminates.
SetPeriod	Sets up a daily, weekly, or monthly period for repeat scheduling.
SetStartDate	Sets the date the schedule becomes effective.
SetTimeInterval	Sets the time interval during a specified day for repeating a schedule.
SetTimeZone	Establishes the time zone for the schedule.
SetTypeOfDaysInPeriod	Sets a day, Monday through Sunday, and its position in the period, such as 1st Monday of the period, for the schedule.


Example

This example shows how to schedule a report to execute and print in one minute.

AcExecuteAndPrintObject eAndp;

eAndp.SetInputObjectName("/Western Region/forecast.rox");

eAndp.SetValuesObjectName("/Western Region/forecast.rov");

eAndp.SetOutputObjectName("/Western Region/forecast.roi",TRUE);

eAndp.SetPrinterName("\\\\lahaina\\HP LASERJET IIP");

m_sendStatus =m_connection->SendRequest(  eAndp, m_timeout);

 AcSchedule schedule;

// Uses todays date

RWCollectableDate startDate;

  schedule.SetStartDate(startDate);

// This schedule ends on 31st Dec, 1999

  RWDate endDate(31,12,99);

  schedule.SetEndDate(endDate);

// Max Duration of this schedule; If duration time is expired this operation

// is aborted

// What time this schedule is started on this day,

  RWTime startTime = RWTime::now() + 60;

  schedule.AddAbsoluteTime(startTime);

  RWOrdered schedules;

  schedules.append(&schedule);

  eAndp.SetSchedule(schedules);

  eAndp.SetPriority(3); // Low priority

  m_sendStatus =m_connection->SendRequest(eAndp, m_timeout);


Member functions of AcSchedule

AcSchedule::AddAbsoluteDate

AcSchedule::AddAbsoluteTime

AcSchedule::AddDayOfMonth

AcSchedule::AddDayOfPeriod

AcSchedule::AddDayOfWeek

AcSchedule::AddDayOfYear

AcSchedule::AddMaskDate

AcSchedule::GetAbsoluteDates

AcSchedule::GetAbsoluteTimes

AcSchedule::GetDaysOfMonth

AcSchedule::GetDaysOfPeriod

AcSchedule::GetDaysOfWeek

AcSchedule::GetDaysOfYear

AcSchedule::GetDurationInSeconds

AcSchedule::GetEndDate

AcSchedule::GetMaskDates

AcSchedule::GetPeriod

AcSchedule::GetStartDate

AcSchedule::GetTimeInterval

AcSchedule::GetTimeZone

AcSchedule::GetTypeOfDayInPeriod

AcSchedule::IsNull

AcSchedule::SetDurationInSeconds

AcSchedule::SetEndDate

AcSchedule::SetPeriod

AcSchedule::SetStartDate

AcSchedule::SetTimeInterval

AcSchedule::SetTimeZone

AcSchedule::SetTypeOfDaysInPeriod


AcSchedule::AddAbsoluteDate

Specifies a particular date for scheduling, rather than a recurring date.

Syntax

void AddAbsoluteDate(const RWCollectableDate& date);

date

Specific date for schedule execution in the form day, month, year (12, 15, 92).


AcSchedule::AddAbsoluteTime

Specifies a time for the schedule to execute during the days that have been added to the schedule.

Syntax

void AddAbsoluteTime(const RWCollectableTime& time);

time

Specific time that the schedule executes.


AcSchedule::AddDayOfMonth

Adds the specified day of the month to the schedule.

Syntax

void AddDayOfMonth(unsigned int day_of_month);

day_of_month

A number from 0-31. A value of 0 corresponds to the last day of any month.

Description

If the day number is greater than the last day of a particular month, the day is not in the schedule. If no days of the week, month, or year have been specified, every day is in the schedule.


AcSchedule::AddDayOfPeriod

Adds the specified day of the period to the schedule.

Syntax

void AddDayOfPeriod(unsigned int day_of_period);

day_of_period

A number from 0 to the end of the period. A value of 0 corresponds to the last day of the period.

Description

If the number of the day is greater than the last day of the period, the day is not in the schedule.


AcSchedule::AddDayOfWeek

Adds the specified day of the week to the set of days of the week for this schedule.

Syntax

void AddDayOfWeek(AcDay day_of_week);

day_of_week

The day of the week, defined as:

AC_SUNDAY or 0

AC_MONDAY or 1

AC_TUESDAY or 2

AC_WEDNESDAY or 3

AC_THURSDAY or 4

AC_FRIDAY or 5

AC_SATURDAY or 6

AC_WEEKDAY

AC_NO_DAY

Description

If you have not specified days of the week, month, or year, the scheduled request runs every day. If AcSchedule::AC_WEEKDAY is specified, the request runs on each of the weekdays.


AcSchedule::AddDayOfYear

Adds the specified day of the year to the schedule. If no days of the week, month, or year have been specified, every day is in the schedule.

Syntax

void AddDayOfYear(const RWCollectableDate& day_of_year);

day_of_year

Use only the month and day of the month to specify the day of the year. The year in the date object is ignored. If the day does not exist during a specific year (31, 2),  the day is not in the schedule.


AcSchedule::AddMaskDate

Adds a mask date to the schedule that specifies a date that must not be in the schedule.

Syntax

void AddMaskDate(const RWCollectableDate& date);

date

The date to avoid. For example, (12, 15, 92).

Description

SetMaskDates allows you to set specific dates to avoid in the schedule. For example, if a request runs each Tuesday, you can set a mask date of December 25 to avoid running the request on Christmas.


AcSchedule::GetAbsoluteDates

Returns the specific dates added to this schedule.

Syntax

RWSet& GetAbsoluteDates();

RWSet  GetAbsoluteDates() const;

Description

If returned as a reference, the set of dates is owned by the AcSchedule object. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of dates. The caller is responsible for deleting the contents of the RWSet.


AcSchedule::GetAbsoluteTimes

Returns the time setting for the schedule to execute during the days added to the schedule.

Syntax

RWSet& GetAbsoluteTimes();

RWSet  GetAbsoluteTimes() const;

Description

If returned as a reference, the AcSchedule object owns the set of times. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of times. The caller is responsible for deleting the contents of the set.


AcSchedule::GetDaysOfMonth

Returns the days of the month for this schedule.

Syntax

RWSet& GetDaysOfMonth();

RWSet  GetDaysOfMonth() const;

Description

If returned as a reference, the AcSchedule object owns the set of days. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of days. The values in the returned set are of type RWCollectableInt*. The caller is responsible for deleting the contents of the set.


AcSchedule::GetDaysOfPeriod

Returns the days of the period set for this schedule.

Syntax

RWSet& GetDaysOfPeriod();

RWSet  GetDaysOfPeriod() const;

Description

If returned as a reference, the AcSchedule object owns the set of days. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of days. The values in the returned set are of type RWCollectableInt*. The caller is responsible for deleting the contents of the set.


AcSchedule::GetDaysOfWeek

Returns the days of the week for this schedule.

Syntax

RWSet& GetDaysOfWeek();

RWSet  GetDaysOfWeek() const;

Description

If returned as a reference, AcObject owns the set of days. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of days. The values in the returned set are of type RWCollectableInt*. The caller is responsible for deleting the contents of the set.


AcSchedule::GetDaysOfYear

Returns the days of the year for this schedule.

Syntax

RWSet& GetDaysOfYear();

RWSet  GetDaysOfYear() const;

Description

If returned as a reference, AcSchedule object owns the set of days. Modification of the set modifies the schedule. The const version of the member function returns a copy of the set of days. The values in the returned set are RWCollectableDate*.


AcSchedule::GetDurationInSeconds

Gets the length of time the schedule is set to run, in seconds.

Syntax

long GetDurationInSeconds() const;

Return value

If a duration of 0 is set, the operation runs as specified by the end date. A duration of -1 specifies an infinite duration. An infinite duration is the default.


AcSchedule::GetEndDate

Gets the date on which the schedule terminates.

Syntax

RWCollectableDate GetEndDate() const;

Description

If an end date is not specified, the operation continues to run as specified by the duration setting.


AcSchedule::GetMaskDates

Returns the dates that cannot be used in the schedule.

Syntax

RWSet& GetMaskDates();

RWSet  GetMaskDates() const;

Description

GetMaskDates allows you to get the mask dates that specify when the request does not run. For example, if a request runs each Tuesday, you can set a mask date of December 25 to avoid running the request on Christmas.

If returned as a reference, the AcSchedule objects owns the set of dates. The const version of the member function returns a copy of the set of dates. The caller is responsible for deleting the contents of the set.


AcSchedule::GetPeriod

Returns the period of time associated with this schedule.

Syntax

void GetPeriod(AcSchedule::AcPeriodUnit& period_unit,
unsigned int& number_of_units) const;

period_unit

The unit of the period. The following are defined values for period units:

AcSchedule::AC_DAYS

AcSchedule::AC_WEEKS

AcSchedule::AC_MONTHS

number_of_units

The number of units in the period.


AcSchedule::GetStartDate

Gets the date the schedule becomes effective.

Syntax

RWCollectableDate GetStartDate() const;


AcSchedule::GetTimeInterval

Returns by reference the time interval specifications for repeating a schedule. The schedule starts at the specified time and is repeated at the intervals until the end of the day.

Syntax

void GetTimeInterval(RWCollectableTime& day_start_time,
RWCollectableTime& day_end_time,
unsigned int& interval_in_seconds) const;

day_start_time

The time to start repeating this schedule. Only the time component of the RWCollectableTime object is used. Date information is ignored.

day_end _time

The time set to end repeating this schedule. Only the time component of the RWCollectableTime object is used. Date information is ignored.

interval_in_seconds

The length of the time interval in seconds.


AcSchedule::GetTimeZone

Gets the time zone that is set for the schedule.

Syntax

RWZone& GetTimeZone() const;

Return value

A reference to the time zone is returned.


AcSchedule::GetTypeOfDayInPeriod

Gets a type of day, Monday through Sunday, in the period for the schedule.

Syntax

void GetTypeOfDayInPeriod(unsigned int& occurrence_number,
AcSchedule::AcDay& type_of_day)

occurrence_number

The number of times the particular day is in the schedule.

type_of_day

Specifies the type of day in the period. The following are the defined values for days:

AcSchedule::AC_SUNDAY

AcSchedule::AC_MONDAY

AcSchedule::AC_TUESDAY

AcSchedule::AC_WEDNESDAY

AcSchedule::AC_THURSDAY

AcSchedule::AC_FRIDAY

AcSchedule::AC_SATURDAY

AcSchedule::AC_WEEKDAY


AcSchedule::IsNull

Returns TRUE if no schedule settings exist. Returns FALSE if this schedule has at least a start date and either an interval or absolute times specified.

Syntax

RWBoolean IsNull() const


AcSchedule::SetDurationInSeconds

Sets how many seconds the repeat schedule request executes.

Syntax

void SetDurationInSeconds(long seconds);

seconds

0 specifies the operation must run as specified by the end date. A duration of -1 specifies an infinite duration. An infinite duration is the default.


AcSchedule::SetEndDate

Example

Sets the end date of the schedule.

Syntax

void SetEndDate(const RWCollectableDate& date);

date

The date in UTC format. If an end date has not been specified, the operation runs as specified by the duration setting.


Example

This example sets this to end on 31st Dec, 1999.

RWDate endDate(31,12,99);

SetEndDate(endDate);


AcSchedule::SetPeriod

Example

Sets up a daily, weekly, or monthly period for repeat scheduling.

Syntax

void SetPeriod(AcSchedule::AcPeriodUnit period_unit,
unsigned int number_of_units);

Description

period_unit

The unit of the period. The following are defined values for period units:

AcSchedule::AC_DAYS

AcSchedule::AC_WEEKS

AcSchedule::AC_MONTHS

number_of_units

The number of units in the period.


Example

This example shows how to call this function to set a schedule for executing a report once monthly.

//Run this every month

//(1=every month; 2= Bimonthly; 4= every quarter;and so on

  schedule.SetPeriod(AcSchedule::AC_MONTHS,1);


AcSchedule::SetStartDate

Example

Sets the date the schedule becomes effective.

Syntax

void SetStartDate(const RWCollectableDate& date);

date

The date in UTC (Universal Time Code) format. If date is NULL, today is the effective start date.


Example

This examples shows how to make today the effective start date.

// Use today's date

RWCollectableDate startDate;

schedule.SetStartDate(startDate);


AcSchedule::SetTimeInterval

Sets the time interval during a specified day for repeatedly executing a schedule.

Syntax

void SetTimeInterval(const RWCollectableTime&  day_start_time,
const RWCollectableTime&  day_end_time,
unsigned int interval_in_seconds);

day_start_time

The time to start repeating this schedule. Only the time component of the RWCollectableTime object is used. Date information is ignored.

day_end _time

The time to end repeating this schedule. Only the time component of the RWCollectableTime object is used. Date information is ignored.

interval_in_seconds

The length of the time interval in seconds.

Description

The schedule runs during the days that have been added to the schedule. The schedule starts at the specified start time of the day and is repeated at intervals until the end of the day.


AcSchedule::SetTimeZone

Sets the time zone for the schedule.

Syntax

void SetTimeZone(const RWZone& zone);

zone

An enumerated data type, such as USMountain, as defined by RWZone.


AcSchedule::SetTypeOfDaysInPeriod

Sets the day and its position in a period for a particular schedule.

Syntax

void SetTypeOfDayInPeriod(unsigned int occurrence_number,
AcSchedule::AcDay type_of_day)

occurrence_number

The number of the occurrence of the type of day that is to be in the schedule.

type_of_day

Specifies the type of day in the period. The following are the defined values for days:

AcSchedule::AC_SUNDAY

AcSchedule::AC_MONDAY

AcSchedule::AC_TUESDAY

AcSchedule::AC_WEDNESDAY

AcSchedule::AC_THURSDAY

AcSchedule::AC_FRIDAY

AcSchedule::AC_SATURDAY

AcSchedule::AC_WEEKDAY

Description

SetTypeOfDaysInPeriod sets the day and where it occurs in a schedule. For example, if you want the 3rd Tuesday in the period to be in the schedule, specify the occurrence number as 3 and the type of day as Tuesday. An occurrence number of 0 corresponds to the last occurrence of the type of day.


AcSenderID

Example   Member functions of AcSenderID

Represents a message that contains information that identifies a client.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
GetDateAndTimeOf Connection	Returns the date and time the sender connected to the server
GetHostName	Returns the sender's machine name.
GetIPAddress	Returns the IP address of the sender's machine.
GetName	Returns the name of the sender. If the sender is a desktop client, this is the client's user name.


Example

This example gets a list of the scheduled requests, prints the list of IDs.

m_connection = new AcClientConnection("","Haleakala",

"Administrator","");

RWCollectableString requestId;

AcGetObjectScheduleRequests getreq;

getreq.SetObjectName("/Western Region/forecast.rox");

m_sendStatus = m_connection->SendRequest(getreq, m_timeout);

RWOrdered reqlist = getreq.GetRequestIDs();

RWOrderedIterator l_iter((RWOrdered&) reqlist);

RWCollectableString* l_string;

while (l_string = RW_SAFE_CAST(l_iter(), RWCollectableString,

__RWCOLLECTABLESTRING)) {

cout << "          " << *l_string << endl;

requestId = *l_string;

}

reqlist.clearAndDestroy();

AcGetRequestInformation reqInfo;

reqInfo.SetRequestID(requestId);

m_sendStatus =m_connection->SendRequest(reqInfo, m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

cout << "RequestInfo for Id    : " << requestId << endl;

AcSenderID id = reqInfo.GetSenderID();

cout << "Sender Information    : " << endl;

cout << "    Name              : " << id.GetName() << endl;

cout << "    Host              : " << id.GetHostName() << endl;

cout << "    IP                : " << id.GetIPAddress() << endl;

cout << "    Date+Time         : " << id.GetDateAndTimeOfConnection()

 << endl;

}

The following output from this example prints the following information about the last request in the list:

062297 12:25:25 9

062297 12:28:30 11

Function executed successfully

RequestInfo for Id    : 062297 12:28:30 11

Sender Information    :

Name : Administrator

Host : haleakala

IP : 128.1.1.2

Date+Time : 06/28/97 15:50:54


Member functions of AcSenderID

AcSenderID::GetDateAndTimeOfConnection

AcSenderID::GetHostName

AcSenderID::GetIPAddress

AcSenderID::GetName

AcSenderID::IsClient


AcSenderID::GetDateAndTimeOfConnection

Returns the date and time the sender connected to the server.

Syntax

RWCollectableTime GetDateAndTimeOfConnection() const


AcSenderID::GetHostName

Returns the sender's machine name.

Syntax

RWCollectableString GetHostName() const


AcSenderID::GetIPAddress

Returns the IP address of the sender's machine.

Syntax

RWCollectableString GetIPAddress() const


AcSenderID::GetName

Returns the name of the sender, such as the client's user name.

Syntax

RWCollectableString GetName() const


AcSenderID::IsClient

Returns TRUE if this is the ID of a client. Returns FALSE if this is the ID of a server process.

Syntax

RWBoolean IsClient() const


AcSetChannelProperties

Member functions of AcSetChannelProperties

Defines the properties of a channel for this request.

Description

This class is used in applications that access the Actuate Report Server via the World Wide Web and Actuate Web Agent service, which is added to Netscape or Microsoft Web Server. Web Agent provides a clipping service of sorts called ReportCast Channels. ReportCast channels use push technology to push reports to particular web channels, where interested users can access and view them. With this class, your application can set up properties for web-based channels. Subscribers to a particular channel view reports or other items available on that channel.

For more information, see egclient in the examples directory of the Report Server API.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetChannelProperties	Defines the properties of the channel for this request.


Member functions of AcSetChannelProperties

AcSetChannelProperties::SetChannelProperties


AcSetChannelProperties::SetChannelProperties

Defines the properties of a channel for this request.

Syntax

void SetChannelProperties(const RWOrdered& properties);

properties

The following table lists the channel properties:

Property	Property value
AC_CHANNEL_ITEM_EXPIRATION	Unsigned integer value representing the expiration time in seconds an item remains on this channel before it is removed.
AC_CHANNEL_SUBSCRIPTION_LIST	The channels that users have privileges to subscribe to.
AC_CHANNEL_SMALL_ICON_URL	The URL of the small custom icon for the current channel.
AC_CHANNEL_LARGE_ICON_URL	The URL of the large custom icon for the current channel.
AC_CHANNEL_POLLING_INTERVAL	The number of seconds that elapses until the next time the Report Server refreshes the contents of the channel.
AC_CHANNEL_COMMENT	A description of the channel.


AcSetPrinterOptionDefaults

Member functions of AcSetPrinterOptionDefaults

Creates a message to set the default value of the specified printer options at the system level. For more information, see Printing reports from the API.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetDefaultPrinterFlag	Specifies the named printer as the default printer if set to TRUE. If set to FALSE or not set, then it is ignored.
SetPrinterName	Identifies the printer to be the default printer.
SetPrinterOptionDefaults	Establishes the default options for the printer.
SetPrinterOptions	Establishes the effective printer option given a list of AcProperty objects that is in the same format as the return value of GetPrinterOptions, a member function of AcGetPrinterInformation.
SetUserName	Sets the name of the user. By default the user name of the sender is used.


Member functions of AcSetPrinterOptionDefaults

AcSetPrinterOptionDefaults::SetDefaultPrinterFlag

AcSetPrinterOptionDefaults::SetPrinterName

AcSetPrinterOptionDefaults:: SetPrinterOptionDefaults

AcSetPrinterOptionDefaults::SetPrinterOptions

AcSetPrinterOptionDefaults::SetUserName


AcSetPrinterOptionDefaults::SetDefaultPrinterFlag

Specifies the named printer as the default printer if set to TRUE. If set to FALSE or not set, then it is ignored.

Syntax

void SetDefaultPrinterFlag(Boolean default_printer_flag)

default_printer_flag

TRUE if the default printer is the effective printer.


AcSetPrinterOptionDefaults::SetPrinterName

Identifies the printer to be the default printer name.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer.


AcSetPrinterOptionDefaults:: SetPrinterOptionDefaults

See also

Establishes the default options for the printer.

Syntax

void SetPrinterOptionDefaults(const RWOrdered& options)

options

A list of AcProperty objects.

Description

This function establishes the default options for the printer given an AcProperty list. The name of each element is the name of the option. The value of the element is the list of choices for the option.

The first value in a list of choices is the default value.


See also

AcGetPrinterInformation::GetPrinterOptions


AcSetPrinterOptionDefaults::SetPrinterOptions

See also

Establishes the effective printer options given a list of AcProperty objects.

Syntax

void SetPrinterOptions(const RWOrdered& options)

options

A list of AcProperty objects.

Description

Create the options argument by formatting the list like the return value of the GetPrinterOptions member function of the AcGetPrinterInformation class.


See also

AcGetPrinterInformation::GetPrinterOptions


AcSetPrinterOptionDefaults::SetUserName

Sets the name of the user. By default, the user name of the sender is used.

Syntax

void SetUserName(const RWCollectableString& name)


AcSetUserDefaultPrinterName

Member functions of AcSetUserDefaultPrinterName

Creates a message to set the default printer for a specific user.

Constructor

This class has default and copy constructors.

Public member functions

Member function	Description
SetPrinterName	Identifies the printer to be the default printer.
SetUserName	Sets the name of the user. By default the user name of the sender is used.


Member functions of AcSetUserDefaultPrinterName

AcSetUserDefaultPrinterName::SetUserName

AcSetUserDefaultPrinterName::SetPrinterName


AcSetUserDefaultPrinterName::SetUserName

Sets the name of the user for whom this is the default printer.

Syntax

void SetUserName(const RWCollectableString& name)

name

The user name as known to the Report Encyclopedia. By default, the user name of the sender is used.


AcSetUserDefaultPrinterName::SetPrinterName

Sets the name of the default printer for the user.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer.


AcSetUserPreferences

Example   Member functions of AcSetUserPreferences

Represents a message to set preferences for a user.

Description

Creates a message for the administration server that sets preferences for a specific user. User preferences specify where to send e-mail notifications, user priority levels, and other user-specific information. This procedure replaces any existing preferences, so if the client application is modifying a user's preferences it should first get the current list, modify it, and then set all the preferences.

This is an administrative task that requires the client application to connect to the Report Server as the user whose preferences are to be set or as a user with the administrator role.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetUserName	Sets the name of the user the preferences apply to.
SetPreferences	Sets the preferences in this object for the user specified in SetUserName.


Example

The following example sets two preferences for a user named William, replacing any previous preferences. This code assumes a server connection called m_connection already exists.

RWCollectableString name="William";

RWOrdered propList;

int m_timeout=100000000;

//Build a property list

property.SetName("__AC_USER_EMAIL_ID");

property.SetStringValue("William@actuate.com");

propList.append(new AcProperty(property));

property.SetName("__AC_HOME_FOLDER");

property.SetStringValue("/usr/home/sales");

propList.append(new AcProperty(property));

//Set the preferences

AcSetUserPreferences setUserPrefMsg;

setUserPrefMsg.SetUserName(name);

setUserPrefMsg.SetUserPreferences(propList);

m_sendStatus =m_connection->SendRequest(setUserPrefMsg,
m_timeout);


Member functions of AcSetUserPreferences

AcSetUserPreferences::SetUserName

AcSetUserPreferences::SetPreferences


AcSetUserPreferences::SetUserName

Sets the name of the user that the preferences apply to.

Syntax

void SetUserName(const RWCollectableString& name)

name

The name of a valid user on the administration server.


AcSetUserPreferences::SetPreferences

See also

Sets the preferences in this object for the user specified in SetUserName.

Syntax

void SetPreferences(const Ordered& preferences)

preferences

A list of AcProperty objects that describe the user's preferences.

The following table lists the system properties.

Property	Description
"__AC_USER_EMAIL_ID"	E-mail address for e-mail completion notification.
"__AC_USER_HOME_FOLDER"	User's home folder.
"__AC_USER_NOTIFICATION_ TYPE"	Type of completion notification - 'e-mail' or 'server'.
"__AC_USER_DEFAULT_ OBJECT_PRIVILEGES"	Specifies privileges to set at the time of creation on any object created by the user. The value of the property is a property list. The name of each property in the list is a role ID or user ID, depending on the semantic type of the property. The semantic type of the property must be either AC_SEMANTIC_TYPE_ROLE or AC_SEMANTIC_TYPE_USER.  The value of each property in the list is a string list containing all of the privilege types to be added to the role or user.
"__AC_USER_MAX_PRIORITY"	Only used by the administrator to specify maximum priorities for each user. The value of the property is a property list. The name of each property in the list is a user ID. The value of the property is an unsigned integer that specifies the user's maximum priority.
"__AC_USER_FIRST_VISIBLE_ FOLDER"	Object ID of first visible folder from the end of the last user login. This is the topmost folder visible due to the scroll position.
"__AC_USER_SELECTED_ ITEMS"	String list of object IDs that were selected at end of the last user login.
"__AC_USER_EXPANDED_ FOLDERS"	String list of object IDs of folders that were expanded at the end of the last user login.


See also

AcGetUserPreferences::GetPreferences


AcSetUserPrinterOptionDefaults

Member functions of AcSetUserPrinterOptionDefaults

Creates a message to set the default value of the specified printer options for the user level printer options.

Syntax

AcSetUserPrinterOptionDefaults()

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetPrinterName	Identifies the user's printer to have default options set.
SetUserName	Sets the name of the user whose default printer options are set. By default, this is the user name of the sender.
SetPrinterOptionDefaults	Sets printer options given a list of AcProperty objects that is in the same format as returned by the GetPrinterOptions member function of the AcGetPrinterInformation class.
SetDefaultPrinterFlag	Specifies the named printer as the default, if set to TRUE. If set to FALSE or not set, then it is ignored.


Member functions of AcSetUserPrinterOptionDefaults

AcSetUserPrinterOptionDefaults::SetPrinterName

AcSetUserPrinterOptionDefaults::SetUserName

AcSetUserPrinterOptionDefaults:: SetPrinterOptionDefaults

AcSetUserPrinterOptionDefaults:: SetDefaultPrinterFlag


AcSetUserPrinterOptionDefaults::SetPrinterName

Identifies the user's printer to have default options set.

Syntax

void SetPrinterName(const RWCollectableString& name)

name

The name of the printer.


AcSetUserPrinterOptionDefaults::SetUserName

Sets the name of the user whose default printer options are set. By default, this is the user name of the sender.

Syntax

void SetUserName(const RWCollectableString& name)


AcSetUserPrinterOptionDefaults:: SetPrinterOptionDefaults

Sets printer options given a list of AcProperty objects.

Syntax

void SetPrinterOptionDefaults(const RWOrdered& options)

Description

Create the options argument by formatting the list of AcProperties like the list returned by the GetPrinterOptions member function of the AcGetPrinterInformation.


AcSetUserPrinterOptionDefaults:: SetDefaultPrinterFlag

Specifies the named printer as the default, if set to TRUE. If set to FALSE or not set, it is ignored.

Syntax

void SetDefaultPrinterFlag(RWBoolean default_printer_flag)


AcStopPendingRequest

Member functions of AcStopPendingRequest

Creates a message to request clearing the specified pending request from the list of pending requests. Pending requests are scheduled requests that are in the priority queue but have not yet executed.

Constructor

This class has default and copy constructors only.

Public member functions

Member function	Description
SetRequestID	Identifies the request to be stopped


Member functions of AcStopPendingRequest

AcStopPendingRequest::SetRequestID


AcStopPendingRequest::SetRequestID

Specifies the ID of pending request to stop.

Syntax

void SetRequestIDs(const RWCollectableString& requestID)


Using the Report Server API

The Report Server API is a flexible interface to the features of the Actuate Report Server. Using the API, developers can:

•	Integrate Actuate features into existing corporate applications

•	Automate routine or time-consuming tasks

•	Implement new feature groupings for custom business processes

Developers can use the Administrator Desktop as a model for using the Report Server, but using the programmatic interface requires additional knowledge about server operation. The following topics explain the basic concepts for working with the Report Server API and show how to implement common Report Encyclopedia tasks using API classes. A comprehensive example demonstrates how to write code for common reporting tasks.

See also

Connecting to the Report Encyclopedia
Managing reports from the API
Scheduling and distributing reports from the API
Specifying report notification and distribution
Specifying report privileges
Checking the status of report generation
Printing reports from the API
Managing users, groups, and channels from the API
Managing privileges and roles from the API
System Administration
Interpreting status and error messages
Sample Application


Connecting to the Report Encyclopedia

The gateway to the Report Encyclopedia is the client connection. Every server transaction uses a client connection, either directly or indirectly, as a vehicle for the messaging process inherent to the API.

A client connection is like a server logon. Each connection requires a user name and password and generally remains active for an entire session. The connection pointer is a variable that the client application reuses whenever it makes a server request.

See also

Specifying the IP address for the connection
Making the connection
Using the connection
Specifying the connection pointer
Checking function status
Handling errors or warnings


Specifying the IP address for the connection

The Report Server API asks the name service to map the hostname to an IP address, and when dual network cards are installed on a host, the IP address selected may be the wrong one.

UNIX

On UNIX, to override the name service and connect to a specified IP address, set the environment variable AC_IP_ADDRESS_OVERRIDE to the IP address to which you want to connection.

NT

On NT, to override the name service and connect to a specified IP address, create a registry entry as described in the following procedure.

1	Create an Emergency Repair Disk before making changes to the registry. If you make a mistake, recreate the registry from the disk. For more information, see Windows online help.

2	From the Start menu, select Run and open regedt32.exe.

3	Navigate to HKEY_LOCAL_MACHINE\Software\Actuate\ReportServer

4	Add the following key:

AC_IP_ADDRESS_OVERRIDE

5	Assign the IP address to the value of the key.

6	Save the key.


Making the connection

A single class, called AcClientConnection, implements client connections to the Report Server. The connection process is as follows:

•	Instantiate an AcClientConnection object, passing the Report Server name or IP number, user name, and password as arguments.

•	Save the connection pointer for subsequent server requests.

•	Check the connection status and process any warning or error conditions.

Since server connections implement part of the Report Server security features, the user specified when making the connection must have the privileges necessary to perform the desired action. Third-party applications that integrate Actuate functionality into existing corporate applications can use the Report Server's security by making a new connection to the server for each user request. When only system administrators have access to the client application, you can bypass server security by connecting as a user with the administrator role. Administrators have unlimited access to the Report Encyclopedia.


Using the connection

The procedure for using the connection depends on the type of class used. The Report Server has two types of classes:

•	Task-based

•	Message-based

Both types of classes use messaging to communicate with the Report Server, but task-based classes embed the messaging process in their member functions. AcPersistentObject is the only task-based class in the Report Server API.


Specifying the connection pointer

To specify the connection pointer using AcPersistentObject, pass the connection pointer as an argument in the constructor. To specify the connection pointer using a message-based class, pass the connection pointer when you call AcClientConnection::SendRequest.


Checking function status

To check the status of a function using AcPersistentObject, test the value of AcOperationStatus. To check the status of a function using a message-based class, test the value of AcMessageSendStatus.


Handling errors or warnings

To get information on error or warning conditions using AcPersistentObject, call AcPersistentObject::GetLastMessageSendError. To get information on error or warning conditions using a message-based class, call AcClientConnection::GetMessageSendError.

Interpreting status and error messages.


Managing reports from the API

Administrator Desktop users manage reports from a graphical interface that simplifies the process of adding reports, scheduling execution, distributing results, and other tasks. Through the API, the tasks are reduced to procedures the Report Server and native operating system understand.

See also

Copying reports to the encyclopedia
Copying reports from the encyclopedia
Searching for folders and files
Getting information about files and folders
Setting file dependencies
Deleting files and folders


Copying reports to the encyclopedia

Client applications copy new reports from the native file system to the Report Encyclopedia using AcPersistentObject members and Rogue Wave utilities. The following steps describe the process:

1	Open the source file on the native file system.

Using Rogue Wave file utilities, open the file, determine its size, and copy it into a temporary buffer.

2	Open an existing destination file or create a new one on the Report Server.

Instantiate an AcPersistentObject with the desired destination file name and version number.

3	Copy the file into the encyclopedia.

Write lock the destination file (persistent object) using SetWriteLock, write the temporary buffer to the destination file using Write, and then remove the write lock using UnsetWriteLock.

When specifying the persistent object's name, include the path, report name, and report extension. If the client connection object has a working directory, it will prepend the working directory to the report name and path. For an example, see AcPersistentObject::Write.


Copying reports from the encyclopedia

Client applications copy reports from the Report Server to the native file system using AcPersistentObject members and Rogue Wave utilities. The following steps describe the process:

1	Open the source file on the Report Encyclopedia.

Instantiate an AcPersistentObject using the source file name and version number. Read the file (the persistent object) into a temporary buffer using Read.

2	Open a destination file on the native file system.

Using RogueWave utilities, open a destination file.

3	Copy the file to the native file system.

Read lock the source file (the persistent object) using SetReadLock, write the temporary buffer to the destination file using Rogue Wave utilities, then clear the read lock using UnSetReadLock.


Searching for folders and files

Report Encyclopedia folders have a hierarchy that resembles the computer's native file system, so searching for files or folders often requires querying the Report Encyclopedia for its directory structure and folder contents. In the Report Encyclopedia, folders and files are persistent objects with property lists that describe their location and contents. To navigate the Report Encyclopedia from the API, call the following members of AcPersistentObject:

Programming task	Class member
Search the directory structure for files and folders	AcPersistentObject::GetTree
Identify the contents of a single folder	AcPersistentObject::GetContainedObjects
See also

Understanding GetTree
Using GetContainedObjects


Understanding GetTree

The GetTree member of AcPersistentObject returns a complex set of properties that describe the Report Encyclopedia's folder hierarchy and all contained files. The top-level property returned by GetTree contains a list value that references a list of properties describing the base folder itself, like name and owner.

If the Report Encyclopedia base folder contains files or folders, the list of properties also contains a property with a name equal to AC_OBJECT_BASIC_PROPERTY_CONTAINED_OBJECTS and a value that points to another list of properties that describe the contained objects. This list contains information such as:

•	Name of the file or folder

•	Type of object, such as executable file, report instance, or file folder

•	Owner, version number, and size

•	Creation and last modification date and time

•	Contained objects

Each list of properties can have contained objects, so the property list has a structure like a file system where folders contain other folders in a hierarchical tree.

The following diagram shows the property structure for a single Report Encyclopedia folder containing one report file:

The property returned by AcPersistentObject::GetTree, shown in the upper left of the diagram, points to a list of properties that describe the base folder. The diagram shows three properties, name, owner, and contained objects.

The contained object property indicates that the folder contains other files or folders and has a value that points to another property list with properties similar to the one returned by GetTree. In this case, there is just one property that points to another property list, depicted on the bottom right of the diagram. This list describes the file in the base folder.

When searching for folders and files, traverse the property lists one level at a time, searching for a property with a name that matches your search criteria. Two Rogue Wave utilities are useful when navigating or searching the list of properties:

•	RWOrderedIterator

•	RWOrdered::find

For an example of parsing the properties returned by GetTree, see the listTree example in egclient.


Using GetContainedObjects

The GetContainedObjects member of AcPersistentObject is useful for getting information about all the files and folders in a single Report Server folder. Unlike GetTree, GetContainedObjects returns a list of persistent objects which the client application must subsequently query for additional information.


Getting information about files and folders

In the Report Encyclopedia, files are persistent objects. Information about files falls into the following categories:

•	Basic information like owner, size, and type

•	Dependencies, both dependent on and dependents

•	User and group names to notify when an event occurs

•	Privileges assigned to users and roles

•	Public property names

Client applications access this information through the following members of AcPersistentObject:

Programming task	Class member
Get basic properties	AcPersistentObject::GetBasicProperties
	AcPersistentObject::GetVersion, AcPersistentObject::GetVersions
	AcPersistentObject::GetVersionNumber
	AcPersistentObject::GetID
	AcPersistentObject::GetName
	AcPersistentObject::GetOwner
	AcPersistentObject::GetType
	AcPersistentObject::GetSize
	AcPersistentObject::GetLastModificationUserName
	AcPersistentObject::GetLastModificationDateAndTime
	AcPersistentObject::GetCreationDateAndTime
Get dependencies	AcPersistentObject::GetDependentOn
	AcPersistentObject::GetDependents
Get event information	AcPersistentObject::GetEventUserNames
	AcPersistentObject::GetEventGroupNames
Get privilege information	AcPersistentObject::GetUserNamePrivilegeTypes
	AcPersistentObject::GetRoleNamePrivilegeTypes
Get property list	AcPersistentObject::GetPropertyListNames


Setting file dependencies

The Report Server requires explicit dependencies between the following report files and their report executable:

•	Report instance -- depends on the report executable

The Report Server requires this dependency when presenting an unbundled report instance for viewing.

•	Report parameters -- depends on the report executable

The factory server requires this dependency when generating a report with parameters specified in a parameters file.

The Report Server automatically creates the necessary dependencies for reports it generates. Specifically, unbundled report instances (.ROI) automatically have a dependency on the report executable (.ROX) file that created them. A client application can explicitly set or check dependencies with the following members of AcPersistentObject:

Programming task	Class member
Dependent specification	AcPersistentObject::AddDependent
	AcPersistentObject::DeleteDependent
	AcPersistentObject::DeleteDependents
Dependent management	AcPersistentObject::GetDependents
	AcPersistentObject::GetDependentOn


Deleting files and folders

Client applications can delete files and folders using the Delete member of AcPersistentObject. In a business environment, deletion might destroy valuable historical information. A better strategy is to archive reports, as described in Copying reports from the encyclopedia.


Scheduling and distributing reports from the API

Executing a report creates a new instance of the report instance that has the most up-to-date information. Scheduling report execution simplifies the task of generating and distributing reports on a predetermined timetable. From the API, you can specify when a report executes and how the results are distributed. A report can be run once or periodically and the results can be distributed to users or held in a common Report Encyclopedia folder. This section describes how to perform common report execution and distribution tasks from the API.

See also

Scheduling report generation
Setting parameters
Submitting the report for execution
Report execution


Scheduling report generation

Scheduling is necessary only when specifying multiple report executions. For a single run, the factory server accepts the report request when submitted and executes it according to the report's priority and the server process group directives.

To run a report on a schedule, initialize AcSchedule objects with execution specifications. The resultant list of AcSchedule objects is subsequently passed, by AcExecuteObject or AcExecuteAndPrintObject, to the factory server. AcSchedule has many scheduling options, such as:

•	Start and end dates

•	Time window for execution, for example, at night

•	Frequency of execution, for example, monthly

•	Type of day, like the second Wednesday of the period

Schedules can be arbitrarily complex because the schedule specification to the server is actually a list of schedule specifications. A long list of schedules typically specifies certain days during the upcoming year for report generation.


Setting parameters

The Report Server API does not include entry points for changing report parameters from their defaults. Use the Requestor API to set report parameters programmatically. To make a static change to report parameters, change the report values file (.ROV) from the Developers Workbench.


Submitting the report for execution

Client applications use two Report Server classes to request report generation, one for execution only and one for execute and print:

•	AcExecuteObject

•	AcExecuteAndPrintObject

When submitting a report, a client application specifies the following parameters:

•	Input, output, and parameter files

•	Execution priority

•	Schedule

•	User and role privileges for output file

•	Printer options

Use the following members of AcExecuteObject and AcExecuteAndPrintObject to implement this functionality:

Programming task	Class member
Specify file names or IDs	AcExecuteAndPrintObject::SetInputObjectName
	AcExecuteAndPrintObject::SetInputObjectID
	AcExecuteAndPrintObject::SetOutputObjectName
	AcExecuteAndPrintObject::SetValuesObjectName
	AcExecuteAndPrintObject::SetValuesObjectID
Specify execution options	AcExecuteAndPrintObject:: SetOutputObjectVersionName
	AcExecuteAndPrintObject::SetBundledFlag
	AcExecuteAndPrintObject::SetRequestOptions
	AcExecuteAndPrintObject::SetPrinterName
	AcExecuteAndPrintObject::SetPriority
Specify the schedule	AcExecuteAndPrintObject::SetSchedule
Get the request ID	AcExecuteAndPrintObject::GetRequestID
See also

Specifying files for report execution
Specifying execution priority
Scheduling report execution
Setting user and role privileges for the output report
Setting printer options


Specifying files for report execution

The client application must specify a report executable file (.ROX) as the input file and a report instance (.ROI) for the output file. If the report has settable parameters, specify the report values file (.ROV) as well. The executable file contains default values for parameters that it uses if no values file is specified.

Report Encyclopedia file names are fully qualified names that include the folder path and file extensions. For more information on file specifications, see Referring to files--Windows environment.

Report Encyclopedia IDs are generally assigned by the Report Server, so client applications that want to use the ID rather than the name must first retrieve the object's ID using the GetID member of AcPersistentObject. If the client application sets the name, the ID cannot be retrieved.


Specifying execution priority

Reports execute as background processes on a prioritized basis. The application that requests execution can optionally specify the report priority, within the limits for the user, with the SetPriority member of AcExecuteObject and AcExecuteAndPrintObject. The priority has a range of 0 to 1000, with 1000 as the highest priority.


Scheduling report execution

Scheduling a request is optional; unscheduled requests execute immediately. To schedule a request, create a property list describing the schedule and set it with the SetSchedule member of AcExecuteObject or AcExecuteAndPrintObject.


Setting user and role privileges for the output report

Client applications can specify the user and role privileges for the generated report with the SetRequestOptions member of AcExecuteObject or AcExecuteAndPrintObject. The parameter passed to SetRequestOptions is an AcProperty with three levels:

•	Top level

The top level has an AcProperty object with a list value that points to a list of users and roles. This property is distinguished from other top level properties by a name equal to AC_REQUEST_OUTPUT_OBJECT_PRIVILEGES.

•	User or role level

The list of users and roles is a properties list where each property has a name equal to the user or role ID and a list value pointing to a list of privileges.

•	Privilege level

The privilege list for each user or role is an ordered string list with one entry for each privilege, such as "read" or "execute".


Setting printer options

UseSetPrinterName::AcExecuteAndPrintObject to set the printer name. The printer can be any network printer recognized by the Report Server. Options for the print operation are set with the SetRequestOptions member of AcExecuteAndPrintObject. The parameter passed to SetRequestOption is an AcProperty with three levels:

•	Top level

The top level has an AcProperty object with a list value that points to a list of printer options. This property is distinguished from other top level properties by a name equal to AC_PRINTER_ REQUEST_REQUEST_OPTIONS.

•	Printer option level

The list of printer options is a property list where each property has a name equal to one printer option.

If printer options are not set at this request level, the Report Server uses the defaults for the object, user, or system, in that order.


Report execution

When a report executes, the Report Server accesses the data source originally selected by the report developer. The data source must be available for the report execution to complete successfully.

A successful request to the server does not assure that the report will execute or print successfully. To discover the outcome of an execute request, the client must check the status after the factory server has processed the job. For more information, see Checking the status of report generation.


Specifying report notification and distribution

When the Report Server finishes running a report, a notification goes out to the recipients of the new report. The recipients can be one or any combination of the following:

•	Individual users

•	Groups of users

•	Channels

To specify which users receive a notification when the Report Server generates a new report instance, initialize the report executable object (.ROV) using the following members of AcPersistentObject:

Programming task	Class member
Event notification specification	AcPersistentObject::AddChannelNameEventType
	AcPersistentObject::AddGroupNameEventType
	AcPersistentObject::AddUserNameEventType
	AcPersistentObject::DeleteChannelNameEventType
	AcPersistentObject::DeleteEventTypes
	AcPersistentObject::DeleteGroupNameEventType
Event notification management	AcPersistentObject::GetEventChannelNames
	AcPersistentObject::GetEventGroupNames
	AcPersistentObject::GetEventUserNames
	AcPersistentObject::GetChannelNameEventTypes
	AcPersistentObject::GetGroupNameEventTypes
	AcPersistentObject::GetUserNameEventTypes
The event type for report completion is operation completed. The group or user names are any valid groups or users in the Report Encyclopedia. Add or delete users and groups from the report executable one at a time. The new notifications take effect the next time the report is generated.


Specifying report privileges

User and role privileges are a key element of the Report Server security. Clients must have appropriate privileges to be able to perform any action on a Report Encyclopedia item. The following classes specify user and role privileges for Report Encyclopedia objects:

Programming task	Class
User privilege specification	AcAddPrivilegeToUser
	AcDeletePrivilegeFromUser
	AcGetPrivilegesOfUser
Role privilege specification	AcAddPrivilegeToRole
	AcDeletePrivilegeFromRole
	AcGetPrivilegesOfRole
The client application must connect to the Report Server as the owner of the report object, or as a user with grant privilege on the report, to be able to assign privileges to other users. For more information on privileges, see Privilege relationships.


Checking the status of report generation

Client applications can check the status of report generation for three phases of execution:

•	Scheduled

•	Pending

•	Completed

Additionally, report requests can be queried by:

•	Report object

•	Encyclopedia user

•	Channel

The following table lists Report Server classes used to identify report requests and to get detailed status information:

Programming task	Class
Identify requests by channel	AcGetChannelCompletedRequests
Identify requests by object	AcGetObjectCompletedRequests
	AcGetObjectPendingRequests
	AcGetObjectScheduleRequests
Identify requests by user	AcGetUserCompletedRequests
	AcGetUserPendingRequests
	AcGetUserScheduleRequests
Get request information	AcGetRequestInformation
	AcSenderID
AcGetRequestInformation returns the following information, directly or indirectly, about report requests:

•	Information about the sender of the request

•	Information about the schedule for the request

•	Completion status for the request

•	Details about completed requests

The sample application shipped with the Report Server, egclient, shows how to use AcGetRequestInformation to obtain all the information available on a report request.

See also

Deleting status files


Deleting status files

To delete status files use the following request server classes:

Programming task	Class
Deleting status files	AcDeleteRequest
	AcDeleteAllCompletedRequests
	AcDeleteRequestStatusInformation
	AcDeleteRequestInstanceStatusInformation


Printing reports from the API

Printing reports from the API is accomplished with two classes:

•	AcExecuteAndPrintObject

•	AcPrintObject

•	AcProperty

Use the first class to execute the report before printing the results. To print an executed report, use AcPrintObject. The print functionality of AcExecuteAndPrintObject and AcPrintObject is identical. Use AcProperty to set print options, such as AC_PRINTER_OPTION_PRINT_TO_FILE.

See also

Scheduling report printing
Setting print options


Scheduling report printing

Printing can be scheduled for a specific time or at regular intervals. The schedule is set with AcSchedule, an object that is passed as an argument by the SetSchedule member of AcExecuteAndPrintObject or AcPrintObject. For more information about scheduling see Scheduling report generation.


Setting print options

Print options tell the Report Server where to print a report, for example to a postscript file, and which print options to use. Typical print options are:

•	Printer name

•	Number of copies

•	Paper size

•	Paper orientation

•	Print to a file

The Report Server recognizes print specifications at four levels:

•	System

The Report Server has system defaults for print options that it uses if no other print options are specified for the job.

•	User

Users in the Report Encyclopedia may or may not have default print options. When printing a job, the Report Server checks whether the connected user has default print options specified. If so, the user settings override the system settings.

•	Object

Object settings apply to specific report instances. When printing a report, the Report Server checks to see if the report instance has default print options specified. If so, the object print options override the user and system print options.

•	Request

Requests for report generation can include print options. Options supplied with the request override all other default print options.

The following table summarizes the classes for specifying and managing printers and options:

Print level	Class
System	AcGetPrinterInformation
	AcGetPrinterNames
	AcGetPrinterOptionDefaults
	AcSetPrinterOptionDefaults
User	AcGetUserPrinterOptionDefaults
	AcGetUserDefaultPrinterName
	AcSetUserPrinterOptionDefaults
	AcSetUserDefaultPrinterName
Persistent object	AcPersistentObject::GetDefaultPrinterName
	AcPersistentObject::GetPrinterOptionDefaults
	AcPersistentObject::SetDefaultPrinterName
	AcPersistentObject::SetPrinterOptionDefaults
Print request	AcExecuteAndPrintObject::SetPrinterName
	AcExecuteAndPrintObject::SetRequestOptions
	AcPrintObject::SetPrinterName
	AcPrintObject::SetRequestOptions
For example, a client application can invoke each of the following members at different times, but the setting at the request level overrides settings at other levels:

•	AcSetPrinterOptionDefaults::SetPrinterOptions -- system level

•	AcSetUserPrinterOptionDefaults::SetPrinterOptionDefaults -- user level

•	AcPersistentObject::SetPrinterOptionDefaults -- object level

•	AcPrintObject::SetRequestOptions -- request level


Managing users, groups, and channels from the API

Client applications that connect to the Report Server as a user with the administrator role can manage user and group accounts.

See also

Working with users
Working with groups
Working with channels


Working with users

The API supports the following user administration tasks:

•	Add, change, or delete users

•	Set or get the user preferences

•	Set or get default printer and options

•	Query for existing users

•	Administer passwords

The following table lists the classes used to implement these functions.

Programming task	Class
User administration	AcAddUser
	AcChangePassword
	AcChangeUserName
	AcDeleteUser
	AcGetIDFromName
	AcGetNameFromID
	AcGetUserNames
	AcGetUserPreferences
	AcSetUserPreferences
User printer option assignment	AcGetUserPrinterOptionDefaults
	AcGetUserDefaultPrinterName
	AcSetUserPrinterOptionDefaults
	AcSetUserDefaultPrinterName
Assignment of users to roles is described in Role concepts.


Working with groups

The Report Server facilitates event notification with formal groups. The API supports the following group administration tasks:

•	Add or delete groups

•	Add or delete group members

•	Query for existing groups

•	Query for group owners and members

The following table lists the classes used to implement these functions.

Programming task	Class
Group assignment	AcAddGroup
	AcAddUserToGroup
	AcChangeGroupName
	AcDeleteGroup
	AcDeleteUserFromGroup
Group administration	AcGetGroupNames
	AcGetGroupOwner
	AcGetGroupUserNames
For more information on group notification see Specifying report notification and distribution.


Working with channels

The Report Server API includes classes for accessing the Report Encyclopedia via the World Wide Web and Actuate Web Agent service, which is added to Netscape or Microsoft Web Server. Web Agent provides a clipping service of sorts called ReportCast Channels. ReportCast channels use push technology to push reports to particular web channels, where interested users can access and view them. With this class, your application can set up web-based channels. Subscribers to a particular channel view reports or other items available on that channel.

Channels do not deliver an individual report to every recipient. Instead, users read reports from a shared copy via a channel. The API supports the following channel administration tasks:

•	Add or delete channels

•	Query for existing channels

The following table lists the classes used to implement channel functions.

Programming task	Class
Channel assignment	AcAddChannel
	AcDeleteChannel
Channel administration	AcGetChannelNames


Managing privileges and roles from the API

Access to a Report Encyclopedia and the security of its data are based on granting privileges to users directly or through roles. Privileges indicate the operations that users can perform on folders and report items in the Encyclopedia. With the API, you define the user by name when the client application connects to the Report Server using AcClientConnection.

See also

Privilege relationships
Role concepts


Privilege relationships

A privilege is a relationship between a user represented in the client application and an encyclopedia item that entitles the user to perform certain operations on the item. For example, the read privilege means that the user can view or print the item, or see its contents if it is a folder.

See also

Working with privileges
Types of privileges


Working with privileges

By default, everyone has privileges to read the Report Server's home directory and its original subfolders. For all other folders and files, privileges are assigned by either the owner or administrator. The following table lists the classes used to administer report item privileges.

Programming task	Class
System privilege administration	AcAddPrivilege
	AcDeletePrivilege
	AcGetPrivilegeTypes
Privilege assignment	AcAddPrivilegeToUser
	AcDeletePrivilegeFromUser
	AcGetPrivilegesOfUser
Role privilege specification	AcAddPrivilegeToRole
	AcDeletePrivilegeFromRole
	AcGetPrivilegesOfRole
The Report Server has built-in privileges for read, write, delete, execute, visible, and grant. Client applications can add other privileges to the system for custom applications, but the server does not act upon them.


Types of privileges

The following table lists the privileges that client applications can assign to Report Encyclopedia items. Each row describes a single privilege and what that privilege means for different types of items.

Privilege	Item type	Meaning
Read	Report document	Users can view the report document if users also have read privilege on the associated report executable.
	Report executable, report parameter values	Users can view the associated report document if they also have read privilege on the report document.
	All other types	Users can examine the item's properties and view or print the item's contents. If the item is a folder, users can see what it contains. To see the properties of a report executable, users also need execute privilege.
Write	Folder	Users can create new items in the folder, paste items into it, or rename it. Users must also have read privilege on the folder or it is not visible. Users can move the folder to a different containing folder if they have read and write privileges on the destination folder.
	All other types	Users can rename the item. Users must also have read privilege on the item or it is not visible. Users can move the item to a different containing folder if they have read and write privileges on the destination folder.
Delete	Folder	Users can delete the folder if they have delete privilege on all the items in the folder. Users must also have read privilege on the folder or it is not visible.
	All other types	Users can delete the item. Users must also have read privilege on the item or it is not visible.
Execute	Report executable, report parameter value	Users can schedule a new request for the item. Users must also have read privilege on the item or it is not visible.  In addition, users must have read and write privileges to the folder where the generated report document will be stored and to an existing report document if it will be versioned or replaced by the new report document.
Grant	All types	Users can grant any privilege on the item, including the grant privilege, to others. Users must also have read privilege on the item or it is not visible.
Visible	All types	Users can see the names of contained items of a folder, even if there are no other privileges on the folder or items. Users cannot view the items unless they have read permission. Visible privilege is granted to anonymous users of the Web Agent.


Role concepts

A role is a name for a group of privileges. Roles simplify the task of ensuring that the same privileges are granted to a group of users.

Using roles for relating groups of privileges to groups of users reduces the complexity of administration tasks in two ways:

•	The administrator can group privileges for many items into a single role, and assign that role to all users who need those privileges. Modifying the privilege set associated with the role automatically modifies the privileges of all users who are assigned that role.

•	The administrator can assign one or more parents to a role, causing the role to inherit all the privileges of its parents. Modifying the privilege set of the parent automatically modifies the privileges of all inheriting roles. The final set of privileges for a role is the union of all privileges assigned to its parents, plus the privileges assigned directly to it.

With roles created for them, users can assign privileges for folders or files they create but only an administrator can create or modify the definition of roles and decide which users are included in the different roles.

See also

Administrators
Working with roles


Administrators

The administrator and administrator role are unique in the following ways:

•	They exist as soon as you install the Report Server.

•	They cannot be deleted.

•	Initially, the administrator is the only role that can add, modify, and delete administration items, including users. The administrator can create new roles that have the administrator role as their parent, allowing the new roles to have the same capabilities as the administrator role.

The administrator automatically becomes the owner of any objects belonging to a user whose account is deleted.


Working with roles

The system administrator generally designs and sets up the role hierarchy. Users with grant privilege on the report assign the privilege relationship between the report item and a role. The following table lists the classes used to administer report item privileges at the role level.

Programming task	Class
System role administration	AcAddRole
	AcAddRoleToRole
	AcChangeRoleName
	AcDeleteRole
	AcDeleteRoleFromRole
	AcGetRoleNames
	AcGetRolesOfRole
	AcGetRoleOwner
	AcGetRolesWithRole
User role administration	AcAddRoleToUser
	AcDeleteRoleFromUser
	AcGetRolesOfUser
	AcGetUsersWithRole
Privilege assignment	AcAddPrivilegeToRole
	AcDeletePrivilegeFromRole
	AcGetPrivilegesOfRole
The privilege assignment classes create a relationship between a role and a Report Encyclopedia item. In the Report Encyclopedia, reports use an access list to grant privileges to users or roles selectively.


System Administration

System administration consists of printer and server management tasks.

See also

Printer administration
Server administration


Printer administration

The Actuate Report Server automatically detects local and network printers. Clients can get names, information, and set defaults with the following classes:

Programming task	Class
Printer administration	AcGetPrinterInformation
	AcGetPrinterNames
	AcGetPrinterOptionDefaults
	AcSetPrinterOptionDefaults
System printer defaults only take effect if none are specified for the user, object, or request.


Server administration

Client applications can work directly with servers, but server administration is not required when using most of the Report Server features. The following server classes apply to clients that create their own servers for custom purposes. These classes are not described in the Report Server API Reference.

Programming task	Class
Server administration	AcAddServerName
	AcAddServerType
	AcDeleteServerName
	AcDeleteServerType
	AcGetNumberOfServers
	AcGetServerNames
	AcGetServerParameters
	AcGetServerTypes
	AcGetServerTypeInformation
	AcSetNumberOfServers
	AcSetServerParameters


Interpreting status and error messages

The Report Encyclopedia returns a status indicator that reflects the outcome of each requested operation. The status indicator is one of the following enumerated types, depending on the API class used:

•	Message-based classes -- AcMessageSendStatus

•	Task-based classes -- AcOperationStatus

The majority of Report Encyclopedia classes are message-based because client applications must initialize and send message objects to the server. Task-based classes encapsulate the messaging process. AcPersistentObject is an example of a task-based class.

 In both cases, some member functions return status explicitly as the formal return value and others return it by reference in the member function's argument list. Whenever the server returns a warning or error value, it also returns additional details on the error to the client connection object for subsequent examination.

See also

AcMessageSendStatus
AcOperationStatus
Retrieving Report Server errors
Interpreting Report Server errors


AcMessageSendStatus

Message-based classes return AcMessageSendStatus, an enumerated data type with the following members:

0 = AC_SEND_OK

1 = AC_SEND_WARNING

2 = AC_SEND_WARNING_LAST

3 = AC_SEND_ERROR

The AC_SEND_WARNING_LAST message indicates a warning of greater severity than AC_SEND_WARNING.


AcOperationStatus

Task-based classes return AcOperationStatus, an enumerated data type with the following members:

0 = AC_OK

1 = AC_WARNING

2 = AC_WARNING_LAST

3 = AC_ERROR

The AC_WARNING_LAST message indicates a warning of greater severity than AC_WARNING.


Retrieving Report Server errors

Whenever the server issues a warning or error status, it also delivers additional details to the AcClientConnection object. Client applications retrieve error information two ways, depending on the type of class:

•	GetMessageSendError member of AcClientConnection

•	GetLastMessageSendError member of AcPersistentObject

Both member functions return an AcMessageSendError object that contains details of the error.

See also

GetLastMessageSendError
GetMessageSendError


GetMessageSendError

All message-based classes use AcClientConnection members to communicate with the server. Whenever the server reports an error, the client connection object has error information for the client application to read. Using GetMessageSendError, client applications retrieve error information from the connection object in the form of an AcMessageSendError object.


GetLastMessageSendError

AcPersistentObject has one member dedicated to retrieving errors for other failed members. If a persistent object member returns a warning or error in AcOperationStatus, the client application must call the GetLastMessageSend-Error member of the same persistent object to get the details. GetLastMessage-SendError returns the error information in AcMessageSendError.


Interpreting Report Server errors

Interpreting server errors is important both at runtime and during application debugging. For example, some errors are transient and the application can retry the operation. Others are more complex and require analysis by the developer. This section explains the error structure so developers can better understand unexpected behavior and take appropriate action.

The Report Encyclopedia returns five specific categories of information when an error occurs:

•	Severity

•	Name of error

•	Internal list name

•	Location

•	Description

All error information is contained in the AcMessageSendError object returned by either AcClientConnection::GetMessageSendError or AcPersistentObject::
GetLastMessageSendError. Using members of AcMessageSendError, clients access the error details.

See also

Error severity
Error name
Error list name
Error location
Error description


Error severity

The GetErrorSeverity member function of AcMessageSendError returns the severity level reported by the server. AcErrorSeverity is an enumerated data type with the following values:

0 = AC_ERROR_SEVERITY_NO_ERROR

1 = AC_ERROR_SEVERITY_WARNING

2 = AC_ERROR_SEVERITY_ERROR_RETRYABLE

3 = AC_ERROR_SEVERITY_ERROR_NOT_RETRYABLE

4 = AC_ERROR_SEVERITY_FATAL

AC_ERROR-SEVERITY_NO_ERROR is a placeholder; the server does not create an AcMessageSendError object when there is no error.

AC_ERROR_SEVERITY_WARNING is an event that warrants investigation, but is not severe enough to justify immediate action or user notification. These events are usually logged for analysis later.

AC_ERROR_SEVERITY_ERROR_RETRYABLE is usually a condition that clears by itself. The client application should automatically retry the transaction one or more times.

AC_ERROR_SEVERITY_ERROR_NOT_RETRYABLE can occur for Report Encyclopedia security violations or other non-retryable errors. For this severity level, client applications should report the description of the error to the user or system administrator. In many cases the problem is self-evident, but in more difficult situations, the error name, list name, location, and description member data provide additional details.

AC_ERROR_SEVERITY_FATAL is a serious problem that requires system administrator intervention and corrective action. The error name, list name, location, and description provide additional information for the analysis process.


Error name

The GetErrorName member function of AcMessageSendError returns the name of the error reported by the server. The name is a text string that states the generic problem and segments the problem into message errors and server errors. Some of the error names describe the error in sufficient detail to identify the cause. For example, TIMED_OUT or PERMISSION_DENIED have self-evident meanings. Error names like OPERATION_FAILED need to be associated with the action taken to have meaning.

A good strategy for analyzing error messages is to check all the member data of AcMessageSendError before making a final determination. For more information, see AcMessageSendError.


Error list name

The GetErrorListName member function of AcMessageSendError returns the name of the error list reported by the server. The name is a text string that states the error list associated with the problem. Although error lists are part of the Report Server internal structure, the name often gives clues to the nature of the problem. For example, if the error list is AC_OBJECT_ID and the error description is Object not found, you can infer that the server could not find an object with the specified ID.


Error location

The GetErrorLocation member function of AcMessageSendError returns the name of the Report Server or server procedure that was executing when the error occurred. The error location is useful troubleshooting information.


Error description

The GetErrorDescription member function of AcMessageSendError returns a plain text description of the error. This is often the most useful error message, and should be reported to the application user or system administrator when the error is severe. It is also a valuable analysis tool when combined with the other error messages in AcMessageSendError.


Sample Application

This sample application shows how to combine the Report Server API concepts to implement the following tasks:

•	Connect as an administrator and add two users.

•	Add a report executable and parameter file to the Report Encyclopedia.

•	Make the parameter file dependent on the executable file.

•	Modify the parameter file to specify an unbundled report.

•	Specify user privileges for the report output.

•	Create a schedule for report execution and submit the request.

See also

Connecting to the server
Adding two users
Example
Adding a report executable and parameter file
Setting the bundle parameter in the .ROV file
Initializing AcExecuteAndPrintObject
Running the program
Confirm the results in the Administrator Desktop


Connecting to the server

Using AcClientConnection, the following example connects as the administrator to a Report Server called Haleakala. The example checks for a successful connection and prints an error message if the status indicates a warning or error. When using this example, modify the Report Server name to match an Actuate server on your network.


Adding two users

This example adds William and Naoko as new users. The example requires users registered in the Report Encyclopedia because it specifies distribution of a completed report. If you run the example more than once, be sure to delete the William and Naoko users between runs, to avoid error messages. When an error occurs, the DumpSendError utility sends the contents of the AcSendErrorMessage to the screen.


Example

void main()

{

  #if defined (WIN32)

// Initialize RPC

  AcRpcInit();

  #endif

  AcClientConnection  *m_connection;

  AcClientConnection::AcConnectionStatus c_status;

  RWCollectableString m_userName="Administrator", m_password="";

// Connect to the server

  m_connection = new AcClientConnection("","Haleakala",

  m_userName,m_password);

  c_status = m_connection->GetConnectionStatus();

  if(c_status != AcClientConnection::AC_CONNECTION_OK) {

    cerr << "Bad connection, aborting program. Status: " <<

  AcClientConnectionStatusToString(c_status)  << endl;

    cerr <<"Bad connection, aborting program. Status: " <<(

int) c_status  << endl;

    exit(1);

  }

  else {

    cout << "Connected To Server With  Status  : " << (int) c_status << endl;

  }

// Add two users to the Report Encyclopedia

    RWCollectableString userWilliam ="William", pwWilliam ="pacsix";

    RWCollectableString userNaoko ="Naoko", pwNaoko ="samari";

    EgClientUtil util(m_connection,"Administrator", "");

    AcClientConnection::AcMessageSendStatus m_sendStatus;

    int m_timeout=100000000;

    AcAddUser addUserMsg1;

    addUserMsg1.SetUserName(userWilliam);

    addUserMsg1.SetPassword(pwWilliam);

    m_sendStatus =m_connection->SendRequest(addUserMsg1, m_timeout);

    if (m_sendStatus != AcClientConnection::AC_SEND_OK) {

      util.DumpMessageSendError(m_connection, addUserMsg1);

    }

    AcAddUser addUserMsg2;

    addUserMsg2.SetUserName(userNaoko);

    addUserMsg2.SetPassword(pwNaoko);

    m_sendStatus =m_connection->SendRequest(addUserMsg2, m_timeout);

    if (m_sendStatus != AcClientConnection::AC_SEND_OK) {

      util.DumpMessageSendError(m_connection, addUserMsg2);

    }

    else {cout << " Users added" << endl;

    }

    AcPersistentObject::AcOperationStatus status;

// Add forecast executable to Report Encyclopedia

    RWCollectableString sourceFile =

"D:\\Actuate\\Devwb\\Examples\\Forecast\\forecast.rox";

    RWCollectableString destFile = "/Western Region/forecast.rox";

    AcPersistentObject roxObj(*m_connection, destFile, AC_VERSION_LATEST,

      0,AC_OBJECT_TYPE_ROX, status);

    RWFile file1(sourceFile); file1.SeekToEnd();

long size = file1.CurOffset();

    file1.SeekToBegin(); static char buffer[1000000];

    file1.Read(buffer, size);

    RWCollectableString contents1(buffer, size);

    status = AcPersistentObject::AC_ERROR;

    while (status != AcPersistentObject::AC_OK) {

      status = roxObj.SetWriteLock();

    }

    unsigned long numBytesWritten;

    status = roxObj.Write(0, contents1, numBytesWritten);

    status = roxObj.UnsetWriteLock( TRUE);

// Add forecast parameters file

    sourceFile = "D:\\Actuate\\Devwb\\Examples\\Forecast\\forecast.rov";

    destFile = "/Western Region/forecast.rov";

    AcPersistentObject rovObj(*m_connection, destFile, AC_VERSION_LATEST,

      0,AC_OBJECT_TYPE_ROV, status);

    RWFile file2(sourceFile); file2.SeekToEnd();

size = file2.CurOffset();

    file2.SeekToBegin();

    file2.Read(buffer, size);

    RWCollectableString contents2(buffer, size);

    status = AcPersistentObject::AC_ERROR;

    while (status != AcPersistentObject::AC_OK) {

      status = rovObj.SetWriteLock();

    }

    status = rovObj.Write(0, contents2, numBytesWritten);

    status = rovObj.UnsetWriteLock( TRUE);

cout << " Files added" << endl;

// Make the .ROV dependent on the .ROX

roxObj.AddDependent(rovObj);

// Set bundle paramater in the .ROV file using the requester API

long sessionHandle = AcReqInitialize();

// Connect to the Report Server

long connectionHandle = AcReqConnect("Haleakala", "Administrator", "");

// Read the .ROV from the server.

long fileNumber = AcReqReadFile("rotp://Haleakala/Western/forecast.rov");

AcReqSetValueString(fileNumber, "BundleRox", "False");

AcReqWriteFile(fileNumber, "rotp://Haleakala/Western/forecast.rov");

long status4 = AcReqGetError(fileNumber);

AcReqCloseFile( fileNumber );

AcReqDisconnect(connectionHandle);

AcReqUnInitialize(sessionHandle);

// Initialize execute and print message

    RWCollectableString inputObject = "/Western Region/forecast.rox";

    RWCollectableString valuesObject = "/Western Region/forecast.rov";

    RWCollectableString outputObject = "/Western Region/forecast.roi";

RWCollectableString printerName = "MONSTER";

    AcExecuteAndPrintObject executeObject;

    executeObject.SetInputObjectName(inputObject);

    executeObject.SetValuesObjectName(valuesObject);

    executeObject.SetOutputObjectName(outputObject,TRUE);

executeObject.SetPrinterName(printerName);

executeObject.SetPriority(600); //  priority

// Schedule the report to run 2 minutes from now

AcSchedule schedule;

// Use today's date for start

RWDate startDate;

schedule.SetStartDate(startDate);

// End on 31st Dec, 1999

RWDate endDate(31,12,99);

schedule.SetEndDate(endDate);

// Set the time that this schedule starts on this day.

RWTime startTime = RWTime::now() + 120;

schedule.AddAbsoluteTime(startTime);

RWOrdered schedules;

schedules.append(&schedule);

executeObject.SetSchedule(schedules);

// Get the user ID to use for privilege assignments

AcGetIDFromName getIDFromNameMsg;

getIDFromNameMsg.SetNameType(AcNameRequest::AC_USER);

getIDFromNameMsg.SetName(userWilliam);

m_sendStatus = m_connection->

SendRequest(getIDFromNameMsg, m_timeout);

if (m_sendStatus != AcClientConnection::AC_SEND_OK) {

      util.DumpMessageSendError(m_connection, getIDFromNameMsg);

    }

RWCollectableString idWilliam = getIDFromNameMsg.GetID();

// Specify the user privileges for the generated report

RWOrdered list;

list.clearAndDestroy();

list.append(new RWCollectableString("Read"));

list.append(new RWCollectableString("Execute"));

AcProperty property;

property.SetName(idWilliam);

property.SetSemanticType(AC_SEMANTIC_TYPE_USER);

property.SetStringListValue(list);

list.clearAndDestroy();

list.append(new AcProperty(property));

// Now add this list to Top Level Options property

AcProperty userPrivilegeProperty;

userPrivilegeProperty.SetName(AC_REQUEST_OUTPUT_

OBJECT_PRIVILEGES);

userPrivilegeProperty.SetPropertyListValue(list);

list.clearAndDestroy();

list.append(new AcProperty(userPrivilegeProperty));

executeObject.SetRequestOptions(list);

list.clearAndDestroy();

    m_sendStatus =m_connection->SendRequest(executeObject,m_timeout);

    if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

    cout << " Execute report --  submission completed succesfully" << endl;

    }

  cout << " End of sample" << endl;

  return 0;

}

// End of file

Include the following utility, which dumps AcSendErrorMessage to the screen, in the project desktop to handle messaging errors.

#include "acrsapi.h"

#include "egclient.h"

// Constructor

EgClientUtil::EgClientUtil( AcClientConnection  *connection,

   const RWCollectableString& userName,

   const RWCollectableString& password)

{

}

void

EgClientUtil::DumpMessageSendError(AcClientConnection * connection,

                                   AcMessage& message)

{

  AcMessageSendError error =

    connection->GetMessageSendError(message);

  const char* string =

    AcErrorSeverityToString(error.GetErrorSeverity());

  cerr <<

    "MESSAGE REPLY ERROR" << '\n' <<

  "        Severity    : " << string << '\n' <<

"        Name        : " << error.GetErrorName() << '\n' <<

  "        Location    : " << error.GetErrorLocation() << '\n' <<

"        Description : " << error.GetErrorDescription() << endl;

}


Adding a report executable and parameter file

The Actuate Developer Workbench includes sample files that this example uses. The example copies forecast.rox and forecast.rov from the native system to the Report Encyclopedia. The path on the local file system is hard coded, so change the path to match the location on your file system. Both files are copied to a new folder in the Report Encyclopedia called Western Region and the parameter file is set to depend on the executable file.


Setting the bundle parameter in the .ROV file

Only the Requestor API can set parameters in .ROV or .ROX files. This application creates a Requestor connection to the Report Server, opens forecast.rov, sets the BundleRox value to False, and saves the result back to the Report Encyclopedia. This action specifies an output report that is not bundled with the report executable.

This example does not test for error conditions. For more information on Requester error handling, see Requester API reference, in Actuate Client API Guide.


Initializing AcExecuteAndPrintObject

Initializing the execute and print request has these steps:

•	Specify the input, output, and parameter files.

The input and parameter files are the two files with the base name forecast in the Western Region folder. The output file is the name of the generated report.

•	Specify the printer.

The printer must be one recognized by the Report Server. This example uses MONSTER, but you must substitute a printer name on your network.

•	Specify the priority.

The priority for this request is a little higher than average, 600 on a scale of 1 to 1000.

•	Set a schedule.

Schedules are passed to AcExecuteAndPrintObject as an ordered list of AcSchedule objects. This example specifies three schedule objects: the start date for the request window (now), the end date for the request window (12/21/1999), and the specific request time (in two minutes).

•	Set user privileges.

Privileges for the output report are passed to AcExecuteAndPrintObject as an AcProperty that contains a list of properties describing the users, which themselves contain a string list of privileges. In this example, the user William has read and execute privileges for the output object.

The final step in this process is sending the AcExecuteAndPrintObject to the Report Server. The server responds with ok before the report is generated or printed. To observe execution use the administrator desktop application.


Running the program

To run the example program:

1	Start up a DOS window.

2	At the DOS prompt, type:

<sample>.exe

where sample is the name you chose for the example program. The example program displays the following messages when it executes correctly.

Connected To Server With Status : 0

Users added

Files added

Execute report -- submission completed successfully

End of sample

If run-time errors occur, check the operating environment for your system and update as necessary. If the Report Server encounters errors, the application dumps the contents of AcMessageSendError to the screen.


Confirm the results in the Administrator Desktop

After running the example, launch the Administrator Desktop and watch the Active, Completed, and Scheduled request folders. The report request starts in the Scheduled folder, moves to the Active folder, and ends up in the Completed folder. Verify that the report named forecast successfully completed by checking the Completed folder for the report name with a check mark.

The Western Region folder initially contains the forecast.rox and forecast.roi files that the example copied to the Report Encyclopedia. When execution completes, the folder also contains a copy of the forecast.roi. The contents of the Western Region folder are then as follows:

You can check the report privileges by right clicking on the forecast report executable and selecting properties. Under the privileges tab, you see that the user William has read and execute privileges, as specified from the API:

Finally, check the output from or status of your printer. Verify that the report printed or is scheduled to print.


Report Server API architecture

This section contains background information on the design of the Report Server API. It discusses the organization of classes of the Actuate Report Server API Guide and the servers that constitute the Report Server. This section also discusses properties, requests, schedules, and events. For information on using the API, see Using the Report Server API.The Report Server is actually a number of servers, such as the connection server, request server, administration server, persistent object server, and operation servers. Working with the servers requires an understanding of properties, requests, schedules, events, and messages. Because the Report Server interface is object oriented, developers also need a good understanding of the class hierarchy.

See also

Overview of Report server classes
Functional organization of classes
Report encyclopedia properties
Requesting report generation
Scheduling report generation
Report server components
Report Encyclopedia events


Overview of Report server classes

AcMessage is the root class for most API classes, as shown by the following diagram of the upper-level classes in the hierarchy.

AcMessage, the root class for most API classes, serves as the interface for communicating information from the client to the server. All of the other client interfaces are implemented on top of the messaging subsystem. The messaging system is the interface to the Connection and Request Servers. These servers provide the primary client connection and message brokerage services.


Functional organization of classes

The API classes fall into these functional areas:

•	Administration

•	Connection and request

•	Factory server

•	Persistent Object

•	Printer

See also

Administration classes
Connection and request classes
Factory server classes
Factory server example
Persistent object class
Print server class


Administration classes

Administration classes support the following functions:

•	User and group administration

•	Privilege and role assignments

•	Server and printer management

•	System event definition


Connection and request classes

AcRequest, derived from AcMessage, represents a request for service from a server. For example, a request class encapsulates a message that asks the factory server to execute and print a report item. AcRequest is a base class for deriving classes representing client requests to the server. Usually, you do not instantiate AcRequest directly; its derived classes, such as AcExecuteAndPrintObject, do the work.

AcClientConnection represents a virtual connection between the object making a request and the target server for the request. AcClientConnection usually does not act as a base class for deriving other classes. AcClientConnection makes the client connection to the server. You do instantiate AcClientConnection directly (using new), usually as the first step in writing the application code. You call AcClientConnection::SendRequest to pass message objects. These objects, derived from AcRequest, describe the task with member data. You can recognize the task by the class name of the object.


Factory server classes

Factory server classes, such as AcExecuteObject and AcExecuteAndPrintObject, both derived from AcRequest, fulfill requests for printing, report generation, and other operations.

In the next example, three of the four functions needed for printing reports are inherited by factory server class AcExecuteAndPrintObject from AcOperationRequest and AcExecuteObject.


Factory server example

This example passes an ROX input object to a request to execute and print a report called forecast, along with an ROV object for obtaining database user names, passwords, and other execution options.

#include "acrsapi.h"

int   main(int argc, char* argv[])

{

#if defined (WIN32)

// Initialize RPC

AcRpcInit();

#endif

AcClientConnection  *m_connection;

AcClientConnection::AcConnectionStatus c_status;

RWCollectableString m_userName="Administrator", m_password="";

// Make connection to the server

m_connection = new AcClientConnection("","lahaina",

m_userName,m_password);

c_status = m_connection->GetConnectionStatus();

if(c_status == AcClientConnection::AC_CONNECTION_OK) {

// Test code

RWCollectableString inputObject = "/Eastern Region/forecast.rox";

RWCollectableString valuesObject = "/Eastern Region/forecast.rov";

RWCollectableString outputObject = "/Eastern Region/forecast.roi";

RWCollectableString printerName = "HP LASERJET IIP";

AcClientConnection::AcMessageSendStatus m_sendStatus;

int m_timeout=100000000;

AcExecuteAndPrintObject executeAndPrintObject;

executeAndPrintObject.SetInputObjectName(inputObject);

executeAndPrintObject.SetValuesObjectName(valuesObject);

executeAndPrintObject.SetOutputObjectName(outputObject,TRUE);

executeAndPrintObject.SetPrinterName(printerName);

m_sendStatus =m_connection->SendRequest(

executeAndPrintObject,m_timeout);

if (m_sendStatus == AcClientConnection::AC_SEND_OK) {

cout << " Function executed succesfully" << endl;

}

cerr << "Connection Status  : " << (int) c_status << endl;

cerr << "Operation Status  : " << (int) m_sendStatus << endl;

}

return 0;

}


Persistent object class

AcPersistentObject is a class that administers and manipulates reports and folders. Unlike other Report Server classes, AcPersistentObject is more task- than message-oriented. AcPersistentObject is an object abstraction on top of messaging interfaces. Most member functions in AcPersistentObject cause one or more messages to be sent, while most other classes represent only one specialized message.

AcPersistentObject contains other message classes derived from AcObjectRequest. Objects of these message classes are accessed by AcPersistentObject member functions.


Print server class

AcPrintObject, derived from AcRequest, is the only print server class. This class requests printing the accompanying report item to a file or a printer.

Addressing printers

Clients usually obtain the names of machines on the network from their request server, and query either a print server or the administration server on each machine for the availability of printers. The client then addresses a print request to a particular printer on a specific machine. For more information, see the example in Factory server.


Report encyclopedia properties

All persistent objects have named property lists that are used to store public and administrative information about the object. The named lists can use variable length strings for their names. Property lists consist of name-value pairs: the name of the property and its value. Each value can be a number, a string, or another list--hence it is called a named list. These properties are stored in a repository.

See also

Predefined object properties
Public object properties


Predefined object properties

Predefined object property lists store information used by the server to manage the report items. You access these properties, such as the object ID, indirectly through the API, by calling a function such as AcMessage::GetID.

Property	Description
Global Unique Object ID	Uniquely references an object across all machines. All objects must be associated with an object ID.
Logical or User- Supplied Name	Report items can be named, so the user can specify a name that would not be syntactically allowed by the server OS file system. For directories, the logical name must be the same as the physical directory name in the file system. All objects must have a logical name, such as forecast.
Type	The type of object, either a directory or report items. All objects must have this property.
User ID of Owner	The ID of the user that currently owns the object. All objects must have this property.
Date/Time Created	The date and time the object was created. All objects must have this property.
User ID of Creator	The ID of the user that created this object. Since the ownership of an object can be changed, the creator and owner may be different. All objects must have this property.
Date/Time Last Modified	The date and time of the last modification of this object. All objects must have this property.
User ID of Last Modifier	The ID of the user that last modified this object. All objects must have this property.
Access Control List (Security Information)	A representation of who can do what with this object. All objects must have this property. With each role or user ID listed there is a list of privileges that pertain to this object.
File Name without Path and Version Number	The name of the file that stores the contents of the object. Only report items require this property. The file name does not contain the file system directory path or the version number of this report item.
Version Number	The version number of this object. Only report items have version numbers. The version number is used to augment the file name of the object to guarantee unique file names for all versions of a particular object.
Size	The size of this object. Only report items have this property.
Dependent Object IDs	This is a list of objects that depend on this object. If this object is deleted, all of the dependent objects will have this object deleted from the list of the object they are dependent on. The list of objects dependent on this object must be obtainable by a client at the time this object is deleted. Only report items can have dependents.
Object IDs This Object is Dependent On	This is a list of objects that this object is dependent on. If one of the objects this object is dependent on is deleted, it is removed from this list. Only report items can be dependent on another object.
Event Notification User IDs and Events	A list of user IDs to be notified when an event affects this object.
Development Status	A flag that indicates whether or not this object is under development or if it has been released. For example, a report item under construction is under development.


Public object properties

The public property lists can be used by a client to store any information it needs for an object. These properties can contain any string and list of strings and have no particular server rules governing them. For example, the property string could be a general description of the property.

The object public property list names are defined in util/objprop.h.

Name	Description
AC_SERVER_LOGICAL_ NAME	A single property, as opposed to a list, with a string value specifying the logical name of the server. Use only on the root object. For example, "root".
AC_WEB_AGENT_NAME	A single property with a string value specifying the host name of the web agent for this server. Use on the root object only.
AC_OBJECT_VERSION_ NAME	A single property with the version name of the object.
AC_OBJECT_COMMENT	A single property with the comment for the object.
AC_OBJECT_SCHEDULE_ START_TIME	A single property with an unsigned integer value that specifies the time in UTC (Universal Time Code) of the request that generated this object.
AC_OBJECT_TEMPORARY_ STATUS	A single property with a boolean value that specifies that the object is a temporary object.
AC_OBJECT_CURRENT_ ROI_PAGE_NUMBER	A list of properties. The last property in the list contains the current page number. Found only on an .ROV. Gives page number progress on requests that involve the .ROV.
AC_OBJECT_CURRENT_ ROI_SIZE	A list of properties. The last property in the list contains the current size. Found on an .ROV. Provides size progress information about requests that involve the .ROV.
AC_OBJECT_NUMBER_OF_ PAGES	An unsigned integer value that contains the number of pages in the object.
AC_REPORT_ PARAMETER_START	The start of the .ROP in the .ROX saved on the server. This is actually used as the size of the old .ROX in the Report Server object. Used in an .ROX only.
AC_REPORT_OBJECT_ SIZE	The size of all of the Report Server object that is outside of the structured storage portion of the object. The structured storage part of the object is always the last part of the Report Server object. Used in an .ROX only.
AC_REPORT_IMAGEXX	The start offset and size of the image (bitmap) portion. XX is specified in the ROI. The print server gets the XX from the ROI and locates the dependent ROX object. This property list name has a list of two properties. One is called "AC_IMAGE_START" and another is called "AC_IMAGE_SIZE". Both are integers. Used in an .ROX only.


Requesting report generation

When clients first connect to a server, they access the server machine through a connection server. If the client is an administration client, the connection server passes the client connection to an administration server. If the client is an end-user, the client connection is passed to a request server. All subsequent requests by the client application are sent directly to the administration server or request server.

When a server receives a request, it can:

•	Handle the request and return the results.

•	Reject the request, which causes the request server to put the request back on a request queue for a later retry.

•	Fail the request, which prevents the request from being retried. A failure status is returned for the request.

See also

Setting request priorities
Batch request
Request IDs
Request status information
Request input and output


Setting request priorities

All requests may specify a priority (as allowed by the privileges of the client) and all requests may be specified as batch requests.


Batch request

When you send a request, the connection server looks for a request server that can handle it. It considers factors such as the request's priority and whether or not it is a batch request.

If the request is not a batch request and a suitable server is not available (for example, the request priority is too low), the request fails and the requesting user is notified. If the request is a batch request, the request server holds it until a suitable server is available.


Request IDs

All running and pending operation requests have unique IDs for request tracking purposes.

A request can specify the ID of an object to be accessed through the persistent object server or a request can contain the actual object or data. The object ID does not have to be referencing an object that is local to the operation server. The persistent object server can access any object, regardless of the location of the object.


Request status information

Request status information is a list of properties that is sent to users who are in a group who must be notified of a particular request's status. Each property in the list corresponds to a single status. Each of the single status properties contains a list of properties that pertain to one status. After deleting a request, do not attempt to obtain status information for it.

The following request status property names are defined in util/msgpname.h:

Name	Description
AC_REQUEST_STATUS_DATE_ AND_TIME	An unsigned integer value that specifies the date and time of the status.
AC_REQUEST_STATUS_ INFORMATION	A string value that contains a description of the status.
AC_REQUEST_STATUS_INPUT_ OBJECT_ID	The ID of the input object for this request at the time the request was created.
AC_REQUEST_STATUS_INPUT_ OBJECT_NAME	The name of the input object for this request at the time the request was created.
AC_REQUEST_STATUS_INPUT_ OBJECT_VERSION_NUMBER	The version number of the input object for this request at the time the request was created.
AC_REQUEST_STATUS_ OUTPUT_OBJECT_ID	A string value that contains the ID of the output object for the request. This property is not in the status if the output object ID is unknown.
AC_REQUEST_STATUS_ OUTPUT_OBJECT_NAME	A string value that contains the name of the output object for the request. This property is not in the status if the output object name is unknown.
AC_REQUEST_STATUS_OUTPUT_ OBJECT_VERSION_NUMBER	An unsigned integer value that contains the version number of the output object for the request. This property is not in the status if the output object version number is unknown.
AC_REQUEST_STATUS_OUTPUT _OBJECT_SIZE	An unsigned integer value that contains the size of the output object for the request. This property is not in the status if the output object size is unknown.
AC_REQUEST_STATUS_ OUTPUT_OBJECT_PAGE_COUNT	An unsigned integer value that contains the page count of the output object for the request. This property is not in the status if the output object page count is unknown.
AC_REQUEST_STATUS_START_ DATE_AND_TIME	An unsigned integer value that specifies the date and time when the request was actually started. Multiple status information lists can be associated with one instance of a request.
AC_REQUEST_COMPLETION_ OPERATION_STATUS	An integer value that represents the completion status of the instance of the request. The values of the integer are defined in util/opstatus.h.


Request input and output

The Report Server API often handles a single request as a sequence of subordinate requests with the lower request piping its output to the input of a subsequent request, such as a factory execution result piping output to a print request. Classes derived from AcRequest query the input and output objects of requests as well as the user information associated with the request. For example, AcGetObjectCompletedRequests can retrieve the IDs of requests made when an ROX was executed by a group of users. AcGetUserCompletedRequests can retrieve the IDs of requests made by a particular user.

Requests receive input objects and return output objects. The following diagram shows an ROI object as an output of one request and an input to another.

See also

Input and output objects


Input and output objects

An input object is a parameter that is passed to the request. An output object is a return value of the request. The example in Factory server, shows setting input and output objects.


Scheduling report generation

You can schedule a request to run:

•	Immediately

•	Once at a specific time

•	On a recurring basis

•	On any specified schedule.

If you do not specify a schedule for a request, the request runs immediately.

The request server manages repeat scheduling of an operation request. The repeat schedules are stored in a repository that the request server reads at start-up. When executing a scheduled request, the request server places it on the priority queue and handles it like any other request.

The persistent object server notifies the request server when the object specified in a repeat schedule moves or gets deleted. If the object is deleted, the repeat schedule information is removed.

The application can query repeat scheduling information and receive reports by user, type of operation, or object operated on.


Report server components

This section describes the administration, connection, operation, persistent object, print, and request servers.

See also

Administration server
Connection server
Operation server
Persistent object server
Request server
Print server
Factory server


Administration server

The administration server:

•	Registers all other servers.

•	Provides authentication services for security.

•	Provides administration services.

•	Uses the persistent object server for accessing report items.

•	Stores and replicates user preferences.

•	Controls how many unnamed operation servers of a particular type are running on a single machine.

•	Registers the settable parameters of other servers and their defaults.

•	Queries an operation server at registration time and stores the operation server's default parameters in an administration server repository.

•	Modifies the operation server's parameters.

•	Listens to a well-known port and can be accessed by an authorized administration client.

Administration servers must be started by the OS either at boot-up time or when another process requests an administration service. Administration parameters can have schedules associated with them so that the parameters of a particular server can change at different times of the day.


Connection server

The connection server:

•	Monitors client connections to a machine and passes the connection to either an administration server or a request server.

•	Serves as the first point of contact between a client and the Report Server system.

•	Provides server connection information to other processes that need access to the request server, administration server, or persistent object server.

•	Receives queries from the request servers, administration servers, and persistent object servers on other machines for the server of the same type on the connection server's machine.

There is one connection server per machine. When first connected, all clients access a server machine through a connection server. If the client is an administration client, the client connection is passed to an administration server. If the client is an end-user or developer, the client connection is passed to a request server. All subsequent requests by the client application are sent directly to the administration server or request server.


Operation server

The operation server:

•	Receives operation requests from request servers.

•	Sends and receives data directly from clients for high-performance data transfer.

•	Provides all of the Actuate-specific functionality to the Report Server system. For example, the factory server is an operation server that knows how to execute Actuate basic and how to create ROIs from ROXs.

There can be several types of operation servers. For example:

•	Factory server

•	Print server

•	Event notification server

The operation servers send and receive data directly from clients for high-performance data transfer. A direct connection between a client and an operation server is established when an operation is scheduled with the operation server.

See also

Comparing named and unnamed operation servers
Starting operation servers


Comparing named and unnamed operation servers

The following characteristics differentiate named from unnamed operation servers:

Named Operation Server	Unnamed
Requests can target named operation servers directly.	Not applicable
Administered individually as well as globally.	Administered on a machine or name basis.
Start automatically when requests sent to them are scheduled to run.	Start on an as-needed basis.
Have their own request queues or are given requests from the priority queues, which are lists that are usually emptied on a FIFO (first-in, first-out) basis.	Receive requests from priority queues.
The number of named and unnamed operation servers cannot exceed the number specified by the administrator.

The names, descriptions, and resource management characteristics and restrictions of operation servers can be queried for a particular machine.

When a client makes a service request that does not target a named operation server, the request server connected to the client routes the request to the request server of the machine for the target object of the operation. For example, if the client requests a run on the report server haleakala, the request goes to the haleakala request queue. The request server prioritizes the request in a priority queue and sends the request to an operation server when any operation server is available and there are no higher priority requests pending. Requests that do not target a specific server name may be handled by any operation server.

The client can specify the name of a specific operation server on any machine to handle a request. The request server places the request on a priority queue local to the specified operation server. Requests can be sent to an operation server that has certain resource management characteristics or restrictions. You can query request servers for the names of available operation servers and their descriptions on any machine the client is connected to.


Starting operation servers

Request servers start operation servers as needed. Named operation servers are started if there is a request targeting the named operation server. When a server starts, it asks the administration server for any parameters that affect its operation.


Persistent object server

The persistent object server:

•	Manages the persistent objects on a machine.

•	Communicates with persistent object servers to transfer data (for copies, moves, and remote object access) and to handle object ID reference updates.

•	Sends and receives data directly from clients for high-performance data transfer.

Persistent object servers must be started by the OS either at boot-up time or when another process requests a persistent object service. There is one persistent object server per machine.


Request server

The request server:

•	Manages and routes operation requests.

•	Prioritizes pending requests.

•	Prioritizes repeat schedules for operation requests.

•	Communicates with request servers on other machines.

•	Forwards requests to request servers on other machines.

•	Requests authorized administration tasks from the administration server.

•	Requests services from the persistent object server.

•	Schedules operations with appropriate operation servers on the local machine, depending on what the request or operation is and what it is operating on.


Print server

The print server:

•	Provides services to the client for sending a printable file, for example an ROI, to any printer on the print server's machine.

•	Receives queries about printers available on various machines.

There may be many print servers running on a machine at one time. There is an administration parameter specifying how many unnamed print servers can be running at one time on a single machine.

When the administration server queries a print server for its default parameters, the print server asks its machine for the printers available. For example, the print server may check the contents of a /usr/spool/lp directory.

Settable parameters registered with the administration server describe the capabilities of available printers. When a printer addition, deletion, or modification is specified to the administration server, it notifies all of the running print servers on the administration server's machine of the change.


Factory server

The factory server is an operation server that generates an ROI from an ROX. Factory servers execute Actuate Basic programs and return the results.

Many factory servers can run on a machine at one time. An administration parameter specifies how many unnamed factory servers can be running at one time on a single machine.


Report Encyclopedia events

An event object contains information that both identifies and classifies it. The following list gives examples of event objects:

•	Object moved or renamed

•	Object read

•	Object copied

•	Object modified (Use to notify a user about a change to an object that the user currently has open for reading)

•	Object versioned

•	Object deleted

•	Object operation failed (there may be many different types of these for different types of operations)

•	Object operation completed (there may be many different types of these for different types of operations)

•	Object ownership changed

•	Object privileges granted

See also

Supported event
Event properties
Event observation
Event notification


Supported event

Object operation completed is the only type of event supported. It is specified as the character string "Operation Status".


Event properties

Persistent objects have the properties event notification user ids and events. These properties are a list of user IDs to notify when an event occurs. The user IDs also have an event list. When an event on the list occurs, the particular user is notified. An empty list of events means the user wants to be notified about all events affecting this object.


Event observation

For security purposes, there are several classes of operations:

•	Read-only operations that don't require factory execution

•	Write operations that don't require factory execution

•	Operations that do require factory execution.

Event observation privileges can be granted for operations of all three classes.

The user who initiates an operation is always able to observe that operation, even if the user doesn't have the observation privileges for the object. Users can specify interest in all events on an object, or a set of the event types.


Event notification

When an event occurs, the server that caused or executed the event passes the event to the request server. The request server notifies the users interested in the event. If an interested user is not logged in at the time, the event information must be stored and forwarded to the user when the user logs in, regardless of which request server the user connects to. Request servers communicate with each other to obtain queued event information for forwarding.