VISUAL WORKFLO DESKTOP ™

VISUAL WORKFLO SERVICES ™

FileNET

Application Developer’s
Guide

Release 3.0

9810995-004
Visual WorkFlo
August 1998

FileNET, @mezzanine, Mezzanine, OSAR, Revise, Saros, ValueNET, Visual WorkFlo,

Watermark, WorkFlo, WorkForce Desktop, and WorkShop are registered trademarks of
FileNET Corporation.

FileNET Ensemble, FileNET IMS Connect, FileNET Sentinel, FileNET:WorkGroup, Auto-

Form, Capture, COLD, Document Warehouse, Foundation for Enterprise Document Man-
FileNET Corporation
agement, Greenbar, Image View, Panagon, Report Manager, Visual WorkFlo/Composer, 3565 Harbor Boulevard
Visual WorkFlo/Conductor, Visual WorkFlo/Performer, WorkFlo/Fax, WorkFlo/Print, and
WorkFlo/Scan, are trademarks of FileNET Corporation. Costa Mesa, California 92626-1420
All other product and brand names are trademarks or registered trademarks of their 800.FILENET (345.3638)
respective companies.
Outside the U.S., call:
Due to continuing product development, product specifications and capabilities are subject
to change without notice. 1 .714.966.3400
Copyright © 1984, 1998 FileNET Corporation. All Rights Reserved. www.filenet.com
Notices
This document contains information proprietary to
FileNET Corporation (FileNET). You may not disclose
or use any proprietary information or reproduce any
part of this document without written permission from
FileNET.

Even though FileNET has tested the hardware and

software and reviewed the documentation, FileNET
makes no warranty or representation, either express
or implied, with respect to the hardware, software, or
documentation, their quality, performance, merchant-
ability, or fitness for a particular purpose. FileNET has
made every effort to keep the information in this man-
ual current and accurate as of the date of publication
or revision. However, FileNET does not guarantee or
imply that this document is error free or accurate with
regard to any particular specification. As a result, this
product is sold as is, and you the purchaser are as-
suming the entire risk as to its quality and perfor-
mance.

In no event will FileNET be liable for direct, indirect,

special, incidental, or consequential damages result-
ing from any defect in the hardware, software, or doc-
umentation, even if advised of the possibility of such
damages. In particular, FileNET shall have no liability
for any programs or data stored in or used with
FileNET products, including the costs of recovering
such programs or data.

Some states do not allow the exclusion or limitations

of liability for incidental or consequential damages, so
the above limitation or exclusion may not apply to
your installation. You may also have other rights that
vary from state to state.

No FileNET agent, dealer, or employee is authorized

to make any modification, extension, or addition to
the above statements.
 Contents

About This Manual 12

When to Use this Guide 13

Related Documents 13

Conventions 14

Education 15

Comments and Suggestions 15

1 Application Development 17
Business Process 18
As-is Business Process 18
To-be Business Process 20
High-volume Sites with Robot Tasks 20
Low-volume Sites 20

Automated Business Process 22

Sample Application, AutoClaim 23
Development Overview 23
Application Category 24
Predevelopment Checklist 25
Basic Work Object Creation 27

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 3

 Contents

Work Object Creation

with the AutoClaim Sample 28

Design Considerations 33
Server-side or Client-side Application 34
Push or Pull (Passive or Active) 34
Passive 35
Active 36
Instruction Sheet: a Process Map 38
Workflow View 39
Development Environment 40
Creative, Administrative, and Active Work Performer
Interface with the API OLE Server 40
Passive Interface with the API OLE Server 42
Passive Interface with Active Access 43

Application Programming Interface 45

Syntax 45
Direct OLE Server Interface 46
Data Type Map
Visual WorkFlo to Visual Basic 5.0 46
Data Type Map
C/C++ Direct Interface to C/C++ Interface Through Wrapper 46
Interface through a OLE Wrapper DLL 47
Array 47
Direct Interface with the OLE Server 47
OLE Wrapper DLL Interface 48
Parameter Direction Mode 48
Return Value - Success Status (RetVal) 49
Handle as an Input Parameter 49
LogonHandle 50
Handle 50

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 4

 Contents

Work Object Identification 52

Logon 52
Visual WorkFlo Session 52
VW_Logon( ) 53
VW_LogonEx( ) 53
SLU Requirement 53

Recovery 54

Security 54

2 Client-side Application 55
Procedure Directory 55

Work Creation 56
Creative Application Development 61
Work Performer Comparison 63

Work Administration 64
Administrative Application Development 64
Query 64
Rapid Access Development 66
Administrative Calls to the API 128
Work Performer Comparison 145

Work Performance 145

Passive 146
Adaptor Use 147
OLE Server Registration 147
Passive Work Performer Development: OLE Server 148
Application Test 161

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 5

 Contents

Passive DLL Work Performer Development 163

Active 166
Active Work Performer Development: OLE Client 167
Application Test 176

Debugging the Application 177

Indicating Operation Success or Failure 178
Calling Log and Statistic APIs 178
Logging API Module Interaction (SVCAPI Trace Logging) 179
Dumping Work Object Contents: NDump Work Performer 179
Running NDump 180
Sample NDump Log 180
Using the UI Button for API Pairs 181

Performance Optimization 181

Reuse 182
Operation and Parameter Tracking 183
Number of Work Queues
and Work Queue Fields 184
wal_purge During Development 184
Locking Work Objects 184
Operation Granularity 185
Validation Checking 185
Sequenced Mode 185
WAL Error Messages 186

3 Server-side Application 187

Client Software on the Server 188

Compilation 189
Work Performer on the AIX 190

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 6

 Contents

Sample AIX Work Performer: VWSample 190

Sample AIX Work Performer: Unattended 213
Work Performer on HPUX 229
Compiler/Runtime Compatibility 230
Sample HPUX Work Performer: VWSample 230
Sample HPUX Work Performer: Unattended 235

Topics Common to Server- and Client-side Applications 240

4 Application Programming Interface 241

Calling the API 241
Locator 242
Calling Sequence 252

Functional Groups 253

API Pairs 253
API Association by Task Group 254
Logon and Logoff 255
Work Object Creation 255
Logging 255
Statistics 256
Sequenced Mode 256
Queue Handling 256
Work Object Access 259
Work Object Binding 259
Work Object Information 259
Data Access 260
Error Handling 261

API Detail Content 262

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 7

 Contents

The APIs 262

VW_AttachToWorkQueue 264
VW_BeginBrowsingWorkQueue 267
VW_BindToUser 272
VW_BrmCreateBrowseModifier 274
VW_BrmFreeBrowseModifier 276
VW_BrmSetLockFilter 277
VW_BrmSetPreSelectRule 279
VW_BrmSetSelectRule 281
VW_BrmSetSortRules 283
VW_Call 288
VW_CheckVersionCompatibility 291
VW_CreateWorkObject 293
VW_CurrentException 295
VW_DetachFromWorkQueue 297
VW_DispatchWorkObject 298
VW_EndBrowsingWorkQueue 299
VW_FreeAccessHandle 300
VW_FreeArrayPtr 303
VW_GetAccessHandle 304
VW_GetArray 307
VW_GetArrayPtr 309
VW_GetArraySize 312
VW_GetBindings 314
VW_GetBoolean 316
VW_GetClassFieldNames 318
VW_GetDataType 320
VW_GetDataTypeArray 322
VW_GetErrorMessage 324
VW_GetErrorMessageSize 325

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 8

 Contents

VW_GetField 326
VW_GetFieldNames 330
VW_GetFieldSize 332
VW_GetFloat 334
VW_GetFPNumber 336
VW_GetHandleType 338
VW_GetInteger 339
VW_GetIsolatedRegion 340
VW_GetMachineId 341
VW_GetOperationName 342
VW_GetOperationNameSize 343
VW_GetParameterMode 344
VW_GetQueueNames 346
VW_GetString 348
VW_GetStringSize 350
VW_GetTime 352
VW_GetWobSignature 354
VW_GetWorkClassNames 355
VW_GetWorkObjectLockStatus 357
VW_GetWorkObjectName 359
VW_GetWorkPerformerClassNames 361
VW_GetWorkPerformerHandle 364
VW_GetWorkQueueDepth 365
VW_LeaveWork 366
VW_LockWorkObject 367
VW_LogMessage 370
VW_Logoff 372
VW_Logon 373
VW_LogonEx 376
VW_LogQueryBegin 381

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 9

 Contents

VW_LogQueryEnd 383
VW_LogQueryNextRecords 384
VW_NextWorkObjectToBrowse 388
VW_QQueryBegin 390
VW_QQueryEnd 398
VW_QQueryNextLockedWorkObject 399
VW_QQueryNextWorkObject 401
VW_QsCreateQuerySpecifier 403
VW_QsFreeQuerySpecifier 414
VW_QueueGetStats 415
VW_RaiseException 419
VW_ReportToWork 421
VW_RosterGetStats 423
VW_SequencedWait 428
VW_SequencedWobFetch 437
VW_SetArray 439
VW_SetArrayPtr 441
VW_SetBoolean 444
VW_SetField 446
VW_SetFloat 448
VW_SetFPNumber 450
VW_SetInteger 452
VW_SetString 454
VW_SetTime 456
VW_TerminateWorkObject 458
VW_UnBind 460
VW_UnlockAndDispatch 461
VW_UnlockWorkObject 462
VW_WobQueryCreate 463
VW_WobQueryEnd 468

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 10

 Contents

VW_WobQueryExecute 469
VW_WobQueryGetAccessHandle 472
VW_WobQueryGetWorkObjectName 475
VW_WobQueryInstrSheet 477
VW_WobQueryOperation 479
VW_WobQueryWorkPerformerClass 481

API Calling Sequence 484

Index 497

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 11

 About This Manual

This manual accompanies Release 3.0 of Panagon Visual WorkFlo to

support Visual WorkFlo application development with samples, guide-
lines, and reference information.

A developer uses the Visual WorkFlo application with Visual WorkFlo

programs, such as Visual WorkFlo/Composer, and other Panagon
components, to automate a business process. Custom business pro-
cess code becomes a Visual WorkFlo application when one of the fol-
lowing occur:

• The application calls the Visual WorkFlo application programming

interface (API).

• The application uses Visual WorkFlo Rapid Access

Development (RAD) controls.

• The Visual WorkFlo/Performer program starts the application.

This manual features a sample Visual WorkFlo application, AutoClaim,

with which it first illustrates development of basic code 1 then gradually
adds Visual WorkFlo functionality. Advanced samples demonstrate Vi-
sual WorkFlo management of even the most challenging tasks.

1.Exercise of the sample requires Microsoft® Visual Basic 5.0 .

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 12

 About This Manual
When to Use this Guide

When to Use this Guide

Use the Visual WorkFlo Application Developer’s Guide during
activities 2 through 4 of the project cycle, as shown below:

Role of Guide Result of this Project Activity a

1 Analysis None As-is business process
2 Design Reference and To-be business process
planning
3 Application Heaviest use in this Automated business process that
construction phase uses Visual WorkFlo applications
and Visual WorkFlo programs
4 Maintenance Planning the next Continuous process improvement
version of the pro- through analysis of the workflow
cess and debug- metrics that Visual WorkFlo cap-
ging tures

a. After project analysis, planners may use the terms “as-is” and “to-
be” in asking the developer to transition their (as-is) business pro-
cess into a (to-be) business process.

Related Documents
Several documents support Visual WorkFlo Release 3.0. This Visual
WorkFlo Application Developer’s Guide and each of the following are
online manuals on the FileNET Panagon Visual WorkFlo Documenta-
tion CD:

Getting Started with Visual WorkFlo

Visual WorkFlo Installation and Administration Handbook

Visual WorkFlo/Composer Handbook

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 13

 About This Manual
Conventions

Visual WorkFlo Release Content Description

Visual WorkFlo Technical Notes

Visual WorkFlo Glossary

Visual WorkFlo/RAD Controls Online Tutorial

Running AutoClaim, an Automated Business Process

Conventions
Visual WorkFlo documentation uses the following conventions:

• Underlined, magenta text as a hyperlink that cross-references one

of the following:

- Another topic in the manual, for example, “When to Use this

Guide” on page 13

- Another manual on the FileNET Panagon Visual WorkFlo Doc-

umentation CD, for example, Visual WorkFlo/Composer Hand-
book

• Abbreviated Visual WorkFlo program names, as follows:

Visual WorkFlo Program Product Name Abbreviation

Visual WorkFlo/Composer Composer
Visual WorkFlo/Conductor Conductor
Visual WorkFlo/Performer Performer
Visual WorkFlo Utilities Utilities

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 14

 About This Manual
Education

• Italic type denotes one of the following:

- Title of a book or manual FileNET recommends for further

information

- Name of an API input parameter for which the developer is to

provide the data

Education
FileNET offers introductory and advanced classes for system adminis-
trators, developers, managers, and support personnel. The classes
combine lecture and lab to provide both conceptual understanding of
the FileNET system and practice in its operation.

For information on class content and schedules, please visit Education

topics in the Services and Support area of:

FileNET’s web site www.filenet.com

Also, contact Education by phone:

Local 714.966.3412
(Orange County, California)

Toll free: 888.FNEDUC8 888.363.3828

Comments and Suggestions

FileNET invites all customers to communicate with the Documentation
group on any question or comment related to FileNET manuals and
on-line help. Please FAX, phone, mail or e-mail your question or com-
ment to Mike Calvert, as follows:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 15

 About This Manual
Comments and Suggestions

Mike Calvert
Director of Documentation
FileNET Corporation (Phone) 714.966.3449
3565 Harbor Boulevard (FAX) 714.850.5859
Costa Mesa, CA 92626-1420 (E-mail) calvert@filenet.com

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 16

 1
1Application Development

Automate a business process with FileNET tools, such as the

following:

• Custom application that calls the Visual WorkFlo API

Use the guidelines in this manual for design.

• Custom application that uses Visual WorkFlo RAD controls

This can access the Visual WorkFlo API through the RAD controls.

• Visual WorkFlo programs

These include Composer, Conductor, Performer, and various utili-

ties. See “Related Documents” on page 13 for information on their
documentation.

• Other Panagon products

These include IDM Desktop, Capture, and Report Manager.

The automated business process creates items of work and processes

them. When your application calls the Visual WorkFlo API VW_
LogonEx( ) or VW_Logon( ), uses the Visual WorkFlo RAD controls, or
runs because Performer starts it, as part of this automation, it be-
comes a Visual WorkFlo application. Visual WorkFlo applications and
Visual WorkFlo programs process work items as Work Objects.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 17

 Application Development
Business Process

Business Process
The application developer’s design and construction responsibility be-
gins once project analysis has produced the business process, a dia-
gram that shows current, “as-is” workflow requirements. The developer
uses the as-is business process to determine where and how to incor-
porate Visual WorkFlo into a to-be business process.

As-is Business Process

The following as-is business process diagrams the workflow require-
ments of the imaginary auto insurance company, AutoSure. AutoSure
headquarters processes claims for automobile accidents, received by:

Agents at headquarters

Agents at remote offices (one with a high volume of claims, the

other with modest volume)

An independent agent who works alone

An analysis team has produced the following diagram, the AutoClaim

As-Is Business Process, to reflect claim workflow at AutoSure. Man-
agement will now ask a developer how to use Visual WorkFlo to auto-
mate this process.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 18

 Application Development
Business Process

Headquarters

☎ Agent

☎ Agent
High-volume ☎ Agent
Remote Office
☎ Agent Independent

Modest-volume
Remote Office

AutoClaim As-is Business Process

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 19

 Application Development
Business Process

To-be Business Process

After review of the as-is business process, AutoSure’s developer de-
signs the to-be business process, which is the plan for using Visual
WorkFlo at Headquarters and at the high-volume, remote office, as
shown in the diagram on the following page.

High-volume Sites with Robot Tasks

AutoSure headquarters must assign and settle claims submitted by its
local agents and by agents of the company’s remote offices. Volume
and workflow complexity at headquarters require Visual WorkFlo. The
to-be business process shows Visual WorkFlo at the high-volume, re-
mote office, also. There, it provides initial processing of claims before
forwarding them to headquarters for settlement. Headquarters and the
high-volume, remote site will have PCs that work like robots—using Vi-
sual WorkFlo to automatically receive, validate, and assign claims in a
workflow. Their Visual WorkFlo systems will communicate over a wide-
area network.

Low-volume Sites
Volume is low enough at one remote office and at the independent
agent’s office that agents at these sites can rely on headquarters’ Vi-
sual WorkFlo software, rather than install it on site. They will create an
item of work locally, but will communicate with Visual WorkFlo at head-
quarters to process it.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 20

 Application Development
Business Process

Headquarters

☎ Agent

Visual WorkFlo

Wide-area Network (WAN)

FAX
Visual WorkFlo

☎ Agent
☎ Agent WorkFlo
Connection
Independent
High-volume
Remote Office IDM Desktop

☎ Agent
Modest-volume
Remote Office

AutoClaim To-be Business Process Features Visual WorkFlo

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 21

 Application Development
Automated Business Process

Remote Office
The to-be business process plans the use of these FileNET products
for the low-volume remote office:

• IDM Desktop

To convert the claims into Work Objects

• WorkFlo Connection (a component of IDM Desktop)

To communicate with Visual WorkFlo

Independent Agent
The independent agent will create a Work Object and FAX it to the Vi-
sual WorkFlo system at headquarters.

Automated Business Process

The developer next automates the to-be business process. For
AutoSure, this means that the developer writes Visual WorkFlo appli-
cations for headquarters and for the high-volume site that:

• Invokes IDM Desktop

• Logs onto Visual WorkFlo by calling the VW_LogonEx( ) API

• Calls subsequent APIs to create and process Work Objects

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 22

 Application Development
Automated Business Process

Sample Application, AutoClaim

This manual features the sample Visual WorkFlo application,
AutoClaim (developed in Visual Basic 5.0), to illustrate automation of
the AutoSure to-be business process.

Development Overview
Automate the to-be business process that requires Visual WorkFlo by
developing a Visual WorkFlo application according to the following
guidelines:

1 Review the categories of Visual WorkFlo application (creative, admin-

istrative, Work Performer), described by the following subsection.

2 Complete the “Predevelopment Checklist” on page 25.

3 Decide whether your application will run on the Visual WorkFlo server
or the PC workstation. See “Server-side or Client-side Application” on
page 34.

4 Consider whether the application will feature push (passive) or

pull (active) user participation. See “Push or Pull (Passive or Active)”
on page 34 for guidelines.

5 Follow the procedures in “Client-side Application” on page 55 or

“Server-side Application” on page 187, depending on your decision in
step 3.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 23

 Application Development
Automated Business Process

Application Category
A Visual WorkFlo application is in one of the following categories:

Creative A creative application:

• Creates a Work Object

• Dispatches a new Work Object to be processed

• Calls APIs in the sequence shown by the blue path in “API Calling
Sequence” on page 484

See “Work Creation” on page 56 for an example of a basic creative Vi-

sual WorkFlo application.

Administrative An administrative application:

• Queries a roster, log, or queue for Work Object data field informa-
tion and process status

• Reads, writes, and updates a Work Object’s data fields

• Administers work through the Visual WorkFlo RAD controls or calls

APIs in the sequence shown by the green path in “API Calling Se-
quence” on page 484.

An administrative application may access a Work Queue, as does a

Work Performer, but it interacts directly with the data fields of a Work
Object, rather than through an Operation.

See “Work Administration” on page 64 for an example of an adminis-

trative Visual WorkFlo application.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 24

 Application Development
Automated Business Process

Work Performer A Work Performer:

• Queries a Work Queue with a queue query or with a browse modi-

fier

• Uses the parameters of its Operation to interact with a Work Ob-

ject’s data fields

• Completes the task represented by an Instruction on an Instruction

Sheet

• Calls APIs in the sequence shown by the queue query in the green
path and by the red path in “API Calling Sequence” on page 484

A Work Performer has the advantage over an administrative applica-

tion that you can re-use it. You don’t need to know the exact name of
the Work Object data field in order to operate upon it, because Visual
WorkFlo maps your Work Performer’s Operation parameter to the
Work Object data field. See“Work Performance” on page 145 for ex-
amples of passive and active Work Performers.

Predevelopment Checklist
Complete the procedures in the following Predevelopment Checklist
before you develop a Visual WorkFlo application.

R Install and configure Visual WorkFlo server software on the server and
Visual WorkFlo client software on the PC workstation and the server.

See the Visual WorkFlo Installation and Administration Handbook for

procedures.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 25

 Application Development
Automated Business Process

R Use Composer to define these:

Work Classes

Work Performer Classes

Isolated region configuration data

For further information about the Composer program, see the Visual
WorkFlo/Composer Handbook.

 Once you have developed the application, but before you run it,
check that following class definition details in your code match
those defined above with Composer:

• Operations

• Adaptor and executable file names

These are only for an application that is a passive Work Per-

former (see “Passive” on page 35 for more information).

• Data fields

• Instruction Sheets

• Index keys

• Work Queue fields

 Within the Composer program, save class definitions and system

configuration information to a common data form description lan-
guage (CDL) file.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 26

 Application Development
Automated Business Process

R Use the Conductor program to transfer the contents of the CDL file to
the Online repository.

For further information about Conductor, see the Visual WorkFlo Instal-
lation and Administration Handbook.

Basic Work Object Creation

The most basic Work Object is one that has the default values—its
data fields have the initial values you defined with Composer. Use such
Work Objects to test an application, for example.

Your Visual WorkFlo installation included the sample application, Auto-

Claim. You can use one of its Work Classes to create a Work Object
that has default values (see the Visual WorkFlo Installation and Admin-
istration Handbook: for details).

1 From the FileNET Panagon Visual WorkFlo menu, select FileNET

Logon and provide your user name and password.

2 From the same menu, select Utilities.

3 From the Visual WorkFlo Utilities window Help menu, select Help Top-
ics, the Contents tab, and the topic Using the Utilities/Creating Work
Objects.
or
Select the Index tab, then the index entry ‘Create Work Object dialog
box’ (leave this open and refer to it as you go to step 4).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 27

 Application Development
Automated Business Process

4 From the Visual WorkFlo Utilities menu, select CreateWorkObjects.

5 Select a Work Class from the choices in the Enter Work Class field.

The Work Classes are in the list because they loaded when you in-
stalled Visual WorkFlo.

6 Select the AutoClaim Work Class. Leave the default, 1, in the Enter
number to create: field. Leave the Save Messages To VWLog File box
unchecked.

7 Click the Create button.

8 When the message ‘Completed Work Object creation.’ displays, click

the Close button.

Note what time it is; you will need this to later identify your Work Ob-
ject. We will look at your Work Object later; for now please proceed
with the next topic.

Work Object Creation

with the AutoClaim Sample
Unless you need to create a Work Object that has default information,
only—during application testing, for example, your application must
feature more customized functionality than that afforded by creating a
Work Object with Utilities. A Visual WorkFlo application provides the
means for developing work in the workflow system.

Soon, you will write your own application to create a Work Object and
dispatch it for processing; however, first create a Work Object using the
sample application, AutoClaim, which you installed when you installed
the Desktop Toolkit option (see Getting Started with Visual WorkFlo ).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 28

 Application Development
Automated Business Process

When you launch the sample’s executable file, autoclaim.exe (in the
Samples file where you installed Visual WorkFlo, it creates work in the
Visual WorkFlo system, lets you populate some or all of a Work Ob-
ject’s data fields, then dispatches the Work Object for processing.

1 From the Start menu, select Programs, then Visual WorkFlo.

2 Select FileNET Logon from the Visual WorkFlo program group menu.

3 Initialize your region.

4 Launch Conductor.

5 From File menu, open transfer source file, samples\autoclaim.cdl.

(This is in the path where you installed Visual WorkFlo from the CD.)

6 Launch autoclaim.exe by double-clicking its icon.

7 From the AutoClaim menu, select AutoClaim.

The AutoSure company’s claim form displays. This is the claim form
the company’s agent fills in when a customer calls in to report an acci-
dent. FileNET used the Visual Basic 5.0 environment to develop auto-
claim.exe, which displays the form and creates a Work Object with the
information the agent enters in the form’s fields.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 29

 Application Development
Automated Business Process

8 Enter a string (characters) in each field except that named

Claim Amount, as follows. In Claim Amount, enter a float (a decimal
number). Pick your own values or use these:

Field Name Example of the value you type

Policy Number 12345
Claim Amount 5500.00
Claim Date 3/4/98
Insured’s Name S. Kahr
Insured’s Address 123 Ocean, Malibu CA 99999
Business Phone 555.555.5555
Driver of Car S. Kahr

9 If there was an injury, tab twice.

This selects the default value, Yes, for Injury.

If there was no injury, click No for Injury.

10 Click the submit button.

The form’s fields clear, indicating that Visual WorkFlo created a Work
Object with the information you entered.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 30

 Application Development
Automated Business Process

Use Conductor to verify that there are two Work Objects in the work-
flow system—the one you just created by running a Visual WorkFlo ap-
plication and the one you created with a utility (see Step 7 on page 28):

1 Select Conductor from the FileNET Panagon Visual WorkFlo programs

list.

In the left pane of the Conductor window, Work Classes, you see a list
of Work Classes (with Work Class selected).

2 Select AutoClaim, since that is the Work Class the autoclaim.exe used
as the template for your Work Object.

The middle pane lists:

Work Objects in the AutoClaim Work Class, among which is the value
you typed into the AutoSure claim form, in the Insured’s Name
field (S. Kahr in the step 8 table, above)

AutoClaim uses the value the agent enters in the Insured’s Name field
as the Work Object ID.

The Field Definitions tab displays:

Left column, Field Names: A list of the names of data fields defined in
the AutoClaim Work Class

Center column, Field Type: A list of the data type of each field named
in the left column

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 31

 Application Development
Automated Business Process

Right column, Initial Value: A list of the default value of each data field
named in the left column

3 Select the Work Object you created (or select S. Kahr).

The right pane displays:

A list of Instruction Sheets defined in or inherited by the AutoClaim

Work Class

The Admin tab displays:

Left column, Field Name: A list of the names of data fields in the
S Kahr Work Object

Right column, Current Value: A list of the values in each data field
named in the left column (look for the values you typed into the fields in
the AutoSure claim form)

4 From the Work Objects list, select the Work Object, aName.

Remember the Work Object you created with the Work Object Creator
utility? The utility assigned it default values. Look In the right-hand col-
umn, Current Value, of the Admin tab for the value that corresponds
with the data field named swcInsuredName. The default value there is
aName.

Check the Current Value column to the right of swcStartTime. This is

when you created the Work Object with Work Object Creator.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 32

 Application Development
Design Considerations

Design Considerations
Design of a Visual WorkFlo application reflects the developer’s deci-
sions regarding the following:

• Method of Work Object creation

See the diagram in “To-be Business Process” on page 20 for an

example in which the user, an independent auto insurance agent,
receives a call from the customer, fills in a claim form on the PC to
record information from the customer’s call (thereby creating a
work item), then FAXes the work item from that PC to a PC at
headquarters.

The developer designs an application that runs on the headquar-

ters PC and recognizes the FAX as a work item which it can take
into Visual WorkFlo and process as a Work Object.

• Application residence on the Visual WorkFlo server or the PC

workstation

• User participation

- The user creates the Work Object with a Visual WorkFlo pro-
gram or application.

- The user participates passively or actively in choosing the se-

quence in which Visual WorkFlo processes Work Objects.

• Workflow view

• Development environment

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 33

 Application Development
Design Considerations

Server-side or Client-side Application

The developer designs a Visual WorkFlo application to run on either
the PC workstation or client software on the Visual WorkFlo server, as
shown in the following diagram.

Visual WorkFlo
Server
Visual WorkFlo
Server Software
Server-side PC Workstation
Visual WorkFlo
Application
Client-side
Visual WorkFlo
Application

The application that runs on the Visual WorkFlo server is an active

Work Performer (never a passive Work Performer). However, on the
PC workstation, an application may be in any category. (See “Applica-
tion Category” on page 24 to review.) The developer places an applica-
tion on the Visual WorkFlo server or PC workstation according to its
requirements. For example, workstation-server transaction is mini-
mized by placing an application on the Visual WorkFlo server when the
application requires minimal user interface.

Push or Pull (Passive or Active)

Review the to-be business process steps that you will automate with a
Work Performer and determine which of these are better automated
with a passive Work Performer and which with an active Work Per-

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 34

 Application Development
Design Considerations

former. Your design determines user participation in Work Object pro-

cess sequencing in one of three ways:

• Passive

Visual WorkFlo/Performer decides the sequence; it pushes work to

the OLE server software.
PC workstation only

• Passive with user access to the sequence

The developer or user accesses OLE server software through an

active Work Performer front end (which can include the use of Vi-
sual WorkFlo RAD controls.
PC workstation only

• Active, predetermined by developer

The developer determines the sequence before running (or before

the user runs) the Work Performer.
Visual WorkFlo server or PC workstation

• Active, determined by user during Work Performer run

The user pulls work to process, thus determining the sequence.

PC workstation only

Passive
A passive Work Performer is the better option when an application is to
reside on the PC workstation and its task processing can run unat-
tended. When you choose a passive Work Performer the following
occur:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 35

 Application Development
Design Considerations

• Visual WorkFlo, rather than the user, selects the next Work Object
and pushes it into process. It maps the Work Object’s data fields to
parameters of the Work Performer’s Operations.

• The user, via the Visual WorkFlo program, Performer, starts and
stops the passive Work Performer which communicates with Visual
WorkFlo through a dynamic link library (DLL) that is an adaptor.
Passive Work Performers run only on the PC workstation, where
Performer resides.

See Performer help and“Adaptor Use” on page 147 for more infor-
mation.

A client-side, passive Work Performer is the better choice, under cer-

tain conditions, even though a server-side active Work Performer mini-
mizes workstation-server transactions on unattended tasks. For
example, legacy programs may require an application that is available
only on a PC or it may be more cost-effective to run a particular Work
Performer on the workstation.

Active
There are two types of active Work Performer:

• Developer or user runs it on the server and processes Work Ob-

jects in the sequence predetermined by the developer

• Developer or user runs it on the PC workstation and processes

Work Objects in the sequence determined by the developer or user
during runtime

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 36

 Application Development
Design Considerations

An active Work Performer:

• Can browse Work Queues and pull the next Work Object for pro-
cessing, rather than working on the next Work Object Visual Work-
Flo pushes to it

The Work Performer must attach to a Work Queue and report to

work for that queue before browsing it.

• Calls APIs to obtain an Operation name and a Work Object handle

• Communicates directly with Visual WorkFlo, rather than through an

adaptor

• Acts as an OLE 1 Automation client and directly uses the services

of the Visual WorkFlo OLE Automation server
or
Is a C/C++ application or program in other code that uses OLE Au-
tomation through an OLE wrapper DLL

See “Development Environment” on page 40 and your Microsoft

documentation for details on OLE Automation access.

Developer Predetermines Sequence

The developer can determine the sequence in which Visual WorkFlo
processes Work Objects before running an application on the
PC workstation or Visual WorkFlo server.

1.OLE is object linking and embedding. OLE Automation is automation according to a

particular set of object-oriented system interfaces and services that standardize how to
build reusable, integrated software components.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 37

 Application Development
Design Considerations

Running an active Work Performer on the Visual WorkFlo server mini-

mizes transaction between workstation and server.

User or Developer Determines Sequence During Run

The developer can write an application that depends on the user’s
choice of sequence while it runs.

Choose an active Work Performer if the user will:

• Stop and start Visual WorkFlo processing

• Browse for and select the next Work Object

• Call APIs to obtain the name of an Operation or a handle to a Work

Object (see “Handle as an Input Parameter” on page 49)

• Use Visual WorkFlo RAD controls

Instruction Sheet: a Process Map

Visual WorkFlo processes Work Objects according to a map, the In-
struction Sheet. An abbreviated Instruction Sheet from the AutoClaim
sample is on the following page.

Visual WorkFlo can process the first step of this Instruction Sheet with-
out human intervention; a passive Work Performer can receive into its
Operation parameters the data field information of the next Work Ob-
ject Visual WorkFlo selects. However, the second step requires an esti-
mator’s review before Visual WorkFlo can further process the Work
Object, so an active Work Performer is the choice for that step.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 38

 Application Development
Design Considerations

Instruction Sheet: a Process Map

See“Passive Work Performer Development: OLE Server” on page 148

for procedures on automating the first step on the process map (a Vi-
sual WorkFlo Instruction Sheet), above. See “Active Work Performer
Development: OLE Client” on page 167 for procedures on automating
the second step.

Workflow View
The user may need a custom view of the workflow (to check the status
of a claim and respond to a customer inquiry, for example). Conductor
affords various views of the workflow and the developer can write an
administrative application to further customize. See “Work Administra-
tion” on page 64 for guidelines.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 39

 Application Development
Design Considerations

Development Environment
Visual WorkFlo supports an application developed in one of the follow-
ing (see the diagrams, below):

• An environment, such as Visual Basic, that interfaces directly with

the OLE Automation server

• C/C++ or other code that interfaces with a C-language OLE wrap-

per DLL to use OLE Automation

• Advanced C/C++ or other code that can interface directly with the
Visual WorkFlo OLE Automation server

Creative, Administrative, and Active Work Performer

Interface with the API OLE Server
The diagram on the following page illustrates non-passive interface op-
tions.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 40

 Application Development
Design Considerations

OLE client
Creative/administrative Creative/administrative
application or active application or active Work
Work Performer Performer in C/C++ or other
in Visual Basic, code that can use a
Power Builder, etc. C-language DLL

OLE client
Header file for C/C++
API-library
DLL interface SVCAPI.H
(OLE wrapper)
VWAPI.DLL

OLE server
API
OLE Automation
executable
VWAPISRV.EXE

Non-passive Interface with the API OLE Server

An application in the creative, administrative, or active Work Performer

category uses OLE Automation in one of the following ways:

• Directly, as a client to Visual WorkFlo’s OLE server,

VWAPISRV.EXE

• Through the C-language version of the API, the VWAPI.DLL

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 41

 Application Development
Design Considerations

The preceding diagram shows how a C/C++ developer can use the
OLE wrapper DLL to access OLE Automation.

Passive Interface with the API OLE Server

A passive Work Performer uses OLE Automation as shown in the dia-
gram below:

OLE server

Passive Work Performer Passive Work Performer

in Visual Basic, in C/C++ or other code
Power Builder, etc. that can use a
C-language DLL

OLE client

OLE Adaptor DLL Adaptor

VWOLEADP.DLL VWDLLADP.DLL

Library that talks to

Trigger Visual WorkFlo/Performer
VWPERF.DLL

Visual WorkFlo/Performer
Passive Interface with the OLE Server

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 42

 Application Development
Design Considerations

A passive Work Performer developed in an environment such as Visual

Basic uses the Visual WorkFlo OLE adaptor, VWOLEADP.DLL; once it
is compiled, it becomes an OLE server. When the developer or user
runs this passive Work Performer, Visual WorkFlo creates an instance
of its Work Performer Class by invoking the executable file associated
with the Executable Script (the progID) you provide with Composer.
(See“Visual WorkFlo Setup” on page 170 for an example.)

A passive Work Performer written to use a C-language DLL uses the

Visual WorkFlo DLL adaptor, VWDLLADP.DLL.

For context, the above diagram shows the relationship of the adaptors
with the FileNET-provided application, Trigger 1, and the Visual WorkFlo
program, Performer, through the library, VWPERF.DLL.

Release 3.0 of Visual WorkFlo supports 32-bit applications. (You may

run a 16-bit Visual WorkFlo application that can directly interface with
the OLE Automation server, but only a 32-bit application can use the
OLE wrapper DLL.)

Passive Interface with Active Access

Enjoy the benefits of the unattended passive Work Performer, but ac-
cess it at will, rather than wait for Performer to run it. Do this by design-
ing a passive Work Performer and active Work Performer pair, that
work together as OLE server and OLE client, respectively. Note that
the active Work Performer can use Visual WorkFlo RAD controls to ac-

1.The number of Triggers there are is the number of passive Work Performers that can
perform simultaneously. Trigger polls queues for work, then hands work off to a Work
Performer. See Visual WorkFlo Technical Notes for details.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 43

 Application Development
Design Considerations

cess the APIs as well as to perform other tasks. (See the Visual Work-
Flo RAD/Controls Online Tutorial.)

The following diagram illustrates these options.

OLE server
OLE client
Passive Work Performer
in Visual Basic, Active Work Performer
Power Builder, etc. in Visual Basic, Power
Builder, C/C++,
or other code

OLE client
OLE Adaptor
VWOLEADP.DLL

Library that talks to

Trigger Visual WorkFlo/Performer
VWPERF.DLL

Visual WorkFlo/Performer
Passive Interface with Active Access

If you design all of your passive Work Performers to be OLE servers to

an active Work Performer front end, you can access them at any time,
rather than wait for Performer to run them.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 44

 Application Development
Application Programming Interface

Application Programming Interface

An application that calls functions (“APIs”) of the Visual WorkFlo appli-
cation programming interface (API) does so in the sequence shown on
the chart, “API Calling Sequence” on page 484.

See “Locator” on page 242 for a list that:

Names Visual WorkFlo APIs alphabetically

Accompanies each API name with an overview of its function

Links you to the details of each API

See “API Association by Task Group” on page 254 for call grouping by
task.

“The APIs” on page 262 details the work each API performs, the rela-
tionship of the API with other APIs and Visual WorkFlo software, data
type reference, and performance tips.

Syntax
Application syntax, such as data type, direction mode, and array han-
dling, depends on the development environment (see “Development
Environment” on page 40). Each API detail in “The APIs” on page 262
lists the parameter data type to use with Visual Basic 5.0 (in direct OLE
server interface) or with code that interfaces with the server through
the OLE wrapper DLL.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 45

 Application Development
Syntax

Direct OLE Server Interface

Environments such as Visual Basic interface directly with the OLE Au-
tomation server. Details in the “The APIs” on page 262 list Visual Ba-
sic’s Object Browser data type in the center column of the input/output
table.

Data Type Map

Visual WorkFlo to Visual Basic 5.0
The data type of your application’s parameters must correspond to that
of the parameters listed in the Composer Operation Definition tab (see
“Visual Basic and Visual WorkFlo Setup Alignment” on page 157) as
follows:

Visual WorkFlo Visual Basic 5.0

Integer Long
Float Double
String String
Boolean Boolean
Time Long

Data Type Map

C/C++ Direct Interface to C/C++ Interface Through Wrapper
In the event that you develop an advanced application in C/C++ that in-
terfaces directly with the OLE server, use the syntax shown in the fol-

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 46

 Application Development
Syntax

lowing table, as it compares with syntax for the C/C++ application that
uses the OLE wrapper DLL.

C/C++ application that uses

C/C++ application that uses OLE Automation through
OLE Automation directly the DLL wrapper
BSTR String
BSTR Character array (char[ ])
BSTR Pointer to character (char *)
BSTR* (pointer to BSTR) Pointer to a pointer to
character (char **)

Interface through a OLE Wrapper DLL

If you access the API through the OLE wrapper (which is a DLL written
in C/C++), FileNET recommends that you use the VW_ data type,
which is a C data type that expedites Visual WorkFlo upgrade and cus-
tomization. (Visual WorkFlo provides it to minimize impact on the de-
veloper when changing the data type.) Each API detail in “The APIs”
on page 262 shows this data type in its C typedef section.

Array
The manner in which your application interfaces with the OLE server
determines the type of array you pass as a parameter.

Direct Interface with the OLE Server

An application that Interfaces directly with the OLE server, rather that
through the DLL wrapper, uses a SAFEARRAY. The SAFEARRAY is
an array that contains not only its data, but the number of its
elements (its “length”). The data type of the array, VARIANT, reflects

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 47

 Application Development
Syntax

that its elements can be of various data types. (The array is “heteroge-
neous.”)

The Visual Basic Object Browser lists an array’s parameter name with-
out a data type and, because a Visual Basic application does not use
the OLE wrapper DLL, the Object Browser shows no array length pa-
rameter.

OLE Wrapper DLL Interface

The C-language version of the API (the wrapper, VWAPI.DLL), uses
the Visual WorkFlo data type VW_VariantArray to pass a heteroge-
neous array as a parameter. Each element of a VW_VariantArray array
is type VW_Variant and includes an identifier plus a data element of
one of the following types:

VW_Integer
VW_Float
VW_String
VW_Boolean
VW_Time

Parameter Direction Mode

The Operation parameter mode is the direction data flows between the
parameter and a Work Object, as follows:

In Data flows from the parameter to the Work Object data field.

Out Data flows from the Work Object data field to the parameter.

Inout Data flows from the parameter to the Work Object data field,
then from the Work Object data field to the parameter.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 48

 Application Development
Syntax

The mode of your application’s parameters must correspond to that of

the parameters listed in the Composer Operation Definition tab (see
“Visual Basic and Visual WorkFlo Setup Alignment” on page 157 for an
example). Visual WorkFlo parameter mode and Visual Basic 5.0 pa-
rameter passing style, map as follows:

Visual WorkFlo Visual Basic 5.0

In ByVal
Out ByRef
Inout ByRef

Return Value - Success Status (RetVal)

Except as indicated in the API details for VW_GetErrorMessage( ) and
VW_GetErrorMessageSize( ), Visual WorkFlo APIs return the success
status of API calls in the RetVal parameter, to which you assign the
data type long, as follows:

Development environment API returns this value in RetVal

Direct OLE server interface Zero (0), if successful
An error number and message, if unsuccessful
Interface through the OLE Zero (0), for VW_Success, if successful
wrapper DLL An error number and message, if unsuccessful

Handle as an Input Parameter

Visual WorkFlo uses identification handles as input to many APIs.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 49

 Application Development
Syntax

LogonHandle
The APIs, VW_LogonEx( ) and VW_Logon( ), return the unique
logon ID, LogonHandle, establishing an application as a Visual
WorkFlo application and allocating resources for its use.

Handle
Many of the API details show the generic parameter, Handle, as input.
To determine what Handle identifies, check its source in the following
table. A call to VW_GetHandleType( ) returns the type of a handle.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 50

 Application Development
Syntax

Return to If you linked to the following table from an API detail and wish to return
API Detail to the detail, please do one of the following:

• Select Bookmark and Page from your View menu, then double-
click on the API name.

• Return through “Locator” on page 242.

Source Handle
VW_ReportToWork( ) WorkPerformerHandle

VW_NextWorkObjectToBrowse( ) for QueueElementHandle

an enqueued Work Object

VW_LockWorkObject( ) for an Opera- OperationHandle

tion parameter
or
VW_SeqeuncedWobFetch( )

VW_CreateWorkObject( ) NewWorkObjectHandle

VW_GetAccessHandle( ) WobAccessHandle
or
VW_WobQueryGetAccess
Handle( ) for an access handle

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 51

 Application Development
Work Object Identification

Work Object Identification

Visual WorkFlo recognizes various forms of identification for a single
Work Object, as follows:

Work Object tag Machine-readable alphanumeric that is in the

database
Work Object name Human-readable string (that Visual WorkFlo
saves to the database as the Work Object tag)
Work Object ID Identity that results when Visual WorkFlo evalu-
ates the Work Object ID expression the user au-
thors with Composer
Work Object number 16-byte binary value

Some application code may use an index, such as one of the following,
to find a Work Object:

QueryCountIndex Identity local to an application batch (see Step 5

on page 133)
Index key Identity used in roster, log, and queue query

Logon
Please see the Visual WorkFlo Installation and Administration Hand-
book for details on Visual WorkFlo logon.

Visual WorkFlo Session

While FileNET Logon provides access to the database on the server,
you must establish a session with Visual WorkFlo in which to run your
application. To do this, call one of the Visual WorkFlo logon APIs, VW_
LogonEx( ) or VW_Logon( ) in your application.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 52

 Application Development
Logon

VW_Logon( )
Running an application that calls VW_Logon( ) causes Visual WorkFlo
to prompt the user for valid user name and password. Once it has
these, Visual WorkFlo establishes a session for that user on the
VWService and in the isolated region defined in the VW.INI file.

VW_Logon( ) establishes a Visual WorkFlo session (with its output,

LogonHandle) only for client-side applications.

VW_LogonEx( )
Running an application that calls VW_LogonEx( ) causes Visual Work-
Flo to establish a session without prompting the user for information, if
the developer provides this information in the API’s UserName , Pass-
word, VWServiceName, and IsolatedRegion input parameters.

Once it has these, Visual WorkFlo establishes a session for that user
on the VWService and in the isolated region of the user’s choice. If the
valid user provides no input to the VWService or IsolatedRegion pa-
rameters, Visual WorkFlo establishes the session on the VWService in
the isolated region defined in the VW.INI file.

VW_LogonEx( ) establishes a Visual WorkFlo session (with its output,

LogonHandle) on either the PC workstation or the server. You must
call it, rather than VW_Logon( ), to establish a session on the server.

SLU Requirement
Session logon with VW_LogonEx( ) in a server-side application uses
a SLU.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 53

 Application Development
Recovery

Recovery
Recovery options depend on the design of your application. For exam-
ple, if your Work Performer executes non-Visual WorkFlo tasks as well
as Visual WorkFlo Operations, you can leave a Work Object locked
during a query, rather than leaving it unlocked and having the Work
Performer go on to another task that depends on the values in the
Work Object. (In this way, you can inspect it, before the Work Per-
former goes to the next task.) Recovery options follow:

Recovery setting
in Composer Result
Automatic The Work Performer locks the Work Object for a query.
The Work Object crashes and is in recovery state. Vi-
sual WorkFlo assumes the work is lost, leaves the
Work Object data fields unchanged, and unlocks the
Work Object.

Manual The Work Performer locks the Work Object for a query.
The Work Object crashes and is in recovery state. Vi-
sual WorkFlo assumes the work is lost, leaves the
Work Object data fields unchanged and leaves the
Work Object locked.

See the Visual WorkFlo Installation and Administration Handbook for

further information on recovery.

Security
Visual WorkFlo manages security by controlling access to your appli-
cations. See the Visual WorkFlo/Composer Handbook for further de-
tails.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 54

 2
2Client-side Application

Follow this chapter’s guidelines to:

• Create, administer, and process work by developing:

- Creative, administrative, and Work Performer applications that

run on the PC workstation

- Active Work Performer applications that run on the Windows

NT server

Procedures for developing active Work Performers that run on AIX

and HP-UX platforms are in Chapter 3, “Server-side Application”
on page 187.

• Develop management and general access views, such as charts

and reports

• Debug the application

• Optimize performance

Procedure Directory
Begin directly with procedures by selecting one of the following, or con-
tinue reading for background.

“Creative Application Development” on page 61

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 55

 Client-side Application
Work Creation

“Administrative Application Development” on page 64

“Passive Work Performer Development: OLE Server” on page 148

“Passive DLL Work Performer Development” on page 163

“Active Work Performer Development: OLE Client” on page 167

“Debugging the Application” on page 177

Use the procedures in this chapter when you have:

• Decided to run a Visual WorkFlo application on the PC workstation

or the NT server

• Completed the “Predevelopment Checklist” on page 25

• Considered whether the user’s participation in Work Object

sequencing will be active or passive

Work Creation
A Visual WorkFlo application develops work in the workflow system, al-
lowing you to create a Work Object and fill in or change the data in its
fields. (Compare this with using the Visual WorkFlo Work Object Cre-
ator utility to create a Work Object with default information only.)

The following sample application creates and dispatches a Work Ob-

ject.

Visual WorkFlo Private Sub Form_Load( )

Work Object
Creation Dim errorCode As Long
Dim LogonHandle As Long

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 56

 Client-side Application
Work Creation

Dim NewWorkObjectHandle As Long

Dim VWServer As New VWApiSrv.VWApiSrv

errorCode=VWServer.VW_LogonEx(“SysAdmin”,”SysAd-
min”,”VWService0:server:FileNET”,1,LogonHandle)

errorCode=VWServer.VW_CreateWorkObject
(LogonHandle,”AutoClaim”,NewWorkObjectHandle)

errorCode=VWServer.VW_DispatchWorkObject
(NewWorkObjectHandle)

errorCode=VWServer.VW_Logoff(LogonHandle)

Set VWServer=Nothing

End Sub

The above Visual WorkFlo application is in the creative category; since

it is not a Work Performer, it is neither active nor passive. See “Applica-
tion Category” on page 24 to review category.

A creative application calls APIs in the sequence shown by the blue

path in “API Calling Sequence” on page 484.

Explanation Explanation of the above (Visual Basic 5.0) code follows:

of Code
The following line runs a routine when you load a form, such as the Au-
toSure claim form:

Private Sub Form_Load( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 57

 Client-side Application
Work Creation

(See the form that displayed when you ran the sample application, au-
toclaim.exe in Step 6 on page 29.)

The following three lines assign data type to parameters the applica-
tion uses in calls to the API:

Dim errorCode As Long

Dim LogonHandle As Long
Dim NewWorkObjectHandle As Long

The following line causes Visual Basic to create an instance of the ob-
ject class OLE server, VWApiSrv.VWApiSrv.

Dim VWServer As New VWApiSrv.VWApiSrv

The VW_LogonEx( ) API, below, returns LogonHandle, one of the pa-

rameters to which you assigned a data type.

errorCode=VWServer.VW_LogonEx(“SysAdmin”,”SysAd-
min”,”VWService0:server:FileNET”,1,LogonHandle)

Components of the above line are as follows:

errorCode= Setting that causes Visual WorkFlo to return a zero, if the

function executes correctly, and to return an error mes-
sage if it does not
VWServer. Object that represents the API server, VWAPISRV.EXE.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 58

 Client-side Application
Work Creation

VW_LogonEx( ) Method (function) that logs the user onto a server and a
VWService and makes the application a Visual WorkFlo
application
This manual also calls the method, which is a function of
the Visual WorkFlo API, an “API.”
See “Logon” on page 52 for information about logging onto
Visual WorkFlo.
“SysAdmin” String the developer input to the API’s parameters, User-
Name and Password
“VWService0: Components of the three-part value that the developer in-
server:FileNET” put to the API parameter, VWServiceName, in the form:
"<ServiceName>:<Domain>:<Organization>"

VWService0
Name of the VWService the developer specified in
ServiceName

server
Name of the server the developer specified in Domain

FileNET
Name of the organization the developer specified in Orga-
nization

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 59

 Client-side Application
Work Creation

1 Number of the developer’s isolated region, input to the

API’s IsolatedRegion parameter
This parameter’s data type is long. (Provide your isolated
region number, rather than the number shown here.)

LogonHandle Name of the parameter through which this API returns the
logon handle, LogonHandle
Use LogonHandle as input in your application’s calls to
subsequent APIs.

Following are three calls to APIs to create a Work Object, dispatch the
Work Object to the first queue, and disconnect the application from the
VWService.

errorCode=VWServer.VW_CreateWorkObject
(LogonHandle,”AutoClaim”,NewWorkObjectHandle)

errorCode=VWServer.VW_DispatchWorkObject
(NewWorkObjectHandle)

errorCode=VWServer.VW_Logoff(LogonHandle)

The developer input the string “AutoClaim” to the WorkClassName pa-

rameter of the first call above. See parameter and data type details for
each API in “The APIs” on page 262.

LogonHandle represents the allocation of resources to the Visual

WorkFlo session. NewWorkObjectHandle represents access to a new
Work Object until VW_DispatchWorkObject dispatches it.

The following lines clean up the server object, left in memory, and end
the application.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 60

 Client-side Application
Work Creation

Set VWServer=Nothing

End Sub

Creative Application Development

Use sample code to create your own Work Object, following the proce-
dures below.

1 Run Visual Basic 5.0 from your Start menu.

2 From the New tab, double-click the Standard EXE icon.

This displays the Project1-Microsoft Visual Basic [design]-

[Form1(Form)] window, inside of which the Form1 window displays.

3 Double-click anywhere within the Form1 window.

This displays the Project1-Microsoft Visual Basic [design] - [Form1

(Code)] window, in which two lines of code appear by default.

4 Between the two lines, mentioned in item 3, copy the sample in “Visual
WorkFlo Work Object Creation” on page 56. (Note that the first and
last lines of the sample are already provided.)

While you are developing code, you can look up a Visual Basic param-
eter data type, as follows:

- Click the Object Browser icon (on the toolbar).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 61

 Client-side Application
Work Creation

- From the Project menu of the Project1- Microsoft Visual Basic [de-
sign] - [Object Browser] window, select References.

- From the References-Project1 window, scroll down until you can

check the box next to Visual WorkFlo API Server 1.0 Type Library.

- Be sure to check the box in addition to selecting the item to estab-

lish the reference.

- Click OK.

- Scroll down in the <All Libraries> window and select VWApiSrv.

- In the Classes pane, select VWApiSrv.

- From the Members of ‘VWApiSrv’ pane, select the API for which
you wish to view Visual Basic parameter data types.

See the following for information about data type for Visual Basic and
other development environments:

“Syntax” on page 45 for reference

“The APIs” on page 262 for:

- Visual Basic Object Browser data type (in the center column of
each API detail table)

- The C typedef for applications that will use the C-language

OLE wrapper DLL (at the end of each detail)

“Locator” on page 242 for an alphabetical list of APIs that links you
to a specific API’s details

5 To run the code, select Start from the Run menu.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 62

 Client-side Application
Work Creation

Once you do this, a Form1 window displays in front of your code. Close
it. Note what time it is (to help identify the Work Object later).

6 Look at the workflow with Conductor, viewing the Work Objects in the
AutoClaim Work Class (you specified “AutoClaim” in the WorkClass-
Name parameter of the VW_CreateWorkObject API).

Do you see three Work Objects now?

• The one you created with the utility

(See the fourth checkbox of the “Predevelopment Checklist” .)

• The one you created with the AutoClaim sample application form

(See “Work Object Creation with the AutoClaim Sample” on

page 28.)

• The one you just created with this application

The Work Object you created with this code has the default value
aName; you can distinguish it by the time you created it (see the
Current Value to the right of the swcStartTime Field Name).

Work Performer Comparison

The creative application runs on the PC workstation. The designation
of active or passive does not apply since it is not a Work Performer.
The creative application can initialize Work Object data fields directly
and it contains no Operation.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 63

 Client-side Application
Work Administration

Work Administration
Once you have created work in the system, check its progress and ad-
minister it with an administrative application. In our AutoClaim sample,
an agent of the AutoSure company would use an administrative appli-
cation to check the status of a claim’s processing when a customer
calls to enquire. AutoSure’s developer could write an administrative ap-
plication that customizes the view of the workflow for the claim pro-
cessing department manager, for example.

Administrative Application Development

A Visual WorkFlo administrative application makes a query to obtain
information and, sometimes, to change Work Object fields (directly
change, rather than change through an Operation).

Use Visual WorkFlo/RAD controls in the application (see “Rapid Ac-

cess Development” on page 66) or design the application so that it
calls APIs, as illustrated in “Administrative Calls to the API” on
page 128.

Query
The application queries one of the following:

Roster
Log
Queue

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 64

 Client-side Application
Work Administration

Roster
Make a roster query to determine whether a Work Object is in process
(see “Sample Roster Query” on page 130 for an example). Compare
the following:

Roster query Query across queues (across Work Performer classes)

Queue query Query across Work Classes in a single queue

Log
Query the log for event records saved on the server (see “Sample Log
Query” on page 135). The user can query the log to determine which
Operations Visual WorkFlo completed on a Work Object. (Compare
this to using the trace log of API activity, saved on the PC.)

Queue
Make a queue query, using a query specifier to access a Work Object.
(See “Sample Queue Query” on page 139.) Once you access the Work
Object’s data fields in this way, you can:

• Obtain and report information about the Work Object

• Change the data fields directly

Note A queue query may be part of an administrative application or part of a

Work Performer. If it is part of a Work Performer, you use the queue
query to access the Work Object of interest, providing the name of the
queue. The Work Performer then changes the Work Object data fields
through Operations, rather than directly. See “Work Performance” on
page 145 for details.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 65

 Client-side Application
Work Administration

Your application may query a queue with a browse modifier, also,

rather than with a query specifier, as part of a Work Performer (see
“VW_BrmCreateBrowseModifier” on page 274.)

Rapid Access Development

Visual WorkFlo/RAD Controls are ActiveX controls that enable rapid
application development (RAD). They reduce demonstration and pilot
development cycle time and facilitate administration and management.

RAD Controls by Task

There are 11 RAD controls. The name of each begins with “FileNET
Visual WorkFlo,” for example, FileNET Visual WorkFlo Field Names
List. They are as follows:

Lists Work Class List

Work Performer Class List
Work Object List by Work Class
Work Object List by Work Performer Class
Field Names List
Field Values List

System information Machine ID Indicator

Isolated Region Indicator

Work Object status Current Operation Status

Work Object Lock Status

Graph Queue Depth Graph

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 66

 Client-side Application
Work Administration

RAD Controls for Sample IN-Basket Application

Use Visual WorkFlo/RAD Controls to administer the AutoClaim sample
application, which follows an automobile insurance claim through the
following workflow process:

1 A customer submits a claim to the insurance company and a creative

application creates a Work Object for the claim.

2 If the claim is for less than a pre-set amount of money and the cus-
tomer has valid insurance, AutoSure pays the claim. An unattended
workstation prints a letter and a check.

3 If the claim is for more than a pre-set amount of money, it goes to an

adjustor for assignment to a field estimator and, if it includes an injury
report, it goes to a medical reviewer.

4 The field estimator examines the claim and estimates the amount of
damage. At the same time (in parallel), the medical reviewer examines
the medical records and estimates amount of medical expense.

5 An adjustor then reviews the field estimate and medical review data
and determines whether AutoSure should settle the claim.

6 An unattended workstation prints a letter and a check.

In this example, the adjustor is responsible for two of the instructions:

• Assign a claim to a field estimator and, in the case of an injury, to a

medical examiner

• Review the reports and other collateral produced by the field esti-
mator and medical examiner to determine whether AutoSure can
settle the claim.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 67

 Client-side Application
Work Administration

Use some of the Visual WorkFlo/RAD controls to expedite administra-

tive application development. Follow the procedures below to:

• Set up the Visual WorkFlo-with-Visual Basic environment

• Create Work Objects, using sample application files

• List work to be done in an “IN basket”

• Drag and drop Visual WorkFlo/RAD controls into the application

• Use a control’s events and properties to enhance the application,

as follows:

Trap errors
Check logon status
Populate lists
Lock, unlock, and dispatch Work Objects
Customize control activation

• Use OLE-Automated Work Performers to assign and review work

Set up the application.

1 Log on to VW Server and run Conductor.

2 From the File menu, select Open Transfer Source File.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 68

 Client-side Application
Work Administration

3 In the Open Image or CDL File dialog box, select and open Auto-
Claim.cdl in:

C:\Program Files\FileNet\Vw\Samples\

Following is part of the screen that displays:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 69

 Client-side Application
Work Administration

4 Click Select All.

5 Click the >> button in the center of the screen.

This transfers the contents of the .cdl file to the Online Repository.
Once the transfer is complete, you see the same thing in the destina-
tion windows that you see in the source windows.

6 Close Conductor.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 70

 Client-side Application
Work Administration

Use the AutoClaim sample application to create Work Objects:

1 Run AutoClaim.exe, which is in the C:\Program Files\FileNet\Vw\Sam-

ples\ directory

2 Create several Work Objects with the Index form that displays:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 71

 Client-side Application
Work Administration

- Fill in the fields with your own data and click Submit.

The fields clear.

- Repeat this once or twice, entering new data each time.

This populates the Online Repository with meaningful data you can
use while developing with the sample application.

3 Click Exit to close the above Index Auto Claim form (which ends Auto-
Claim.exe).

Develop an administrative application that lists work to be done

by the adjustor—a type of “IN” basket.

Follow the procedures below to develop an IN basket, such as that il-

lustrated by Adjustor’s IN Basket Application, below. A Visual WorkFlo
runs an application such as this to obtain a list of work to be done, as-
sign the work, and review the work.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 72

 Client-side Application
Work Administration

Adjustor’s IN Basket Application

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 73

 Client-side Application
Work Administration

Set up the adjustor’s IN basket form with Visual Basic 5.0:

1 Run Visual Basic 5.0.

2 In the New Project window, double-click the Standard EXE icon to be-
gin development of an executable.

Compare this to selecting the ActiveX icon to develop an OLE server

(see “Passive Work Performer Development: OLE Server” on
page 148). The Form1 window displays inside the Project1 window:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 74

 Client-side Application
Work Administration

3 Click near the borders of the forms and use their “handles” to enlarge
the them (so that you have enough space to work in them).

Place Visual WorkFlo/RAD controls into the toolbox, displayed to

the left of the forms:

1 From the Project menu, select Components.

In the Controls tab of the Components window, Visual Basic lists all
controls registered in the Windows operating system. (When you in-
stalled Visual WorkFlo, the Visual WorkFlo/RAD controls automatically
registered; so, they display in this list.)

2 Click in the checkbox to the left of the following controls:

FileNET Visual WorkFlo Isolated Region Indicator

FileNET Visual WorkFlo Machine ID Indicator
FileNET Visual WorkFlo Work Performer Class List

Before clicking OK, inspect the toolbar so that you can compare the
way it looks now with the way it will look after selecting these compo-
nents.

3 Click OK.

An icon for each of the above controls now displays in the toolbar. (As
with other components in the toolbar, you can see which icon repre-
sents which control by pausing the cursor momentarily over each until
its label displays.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 75

 Client-side Application
Work Administration

Add RAD controls to the application, using their toolbox icons:

1 Click a RAD control icon once, move the cursor onto Form1, and draw
a square with it where you want the control to appear, using the “Adjus-
tor’s IN Basket Application” on page 73 as a model for sizing and posi-
tioning.

Repeat for the other two controls until your application looks similar to
the following:

Play button

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 76

 Client-side Application
Work Administration

2 Check to see that you are still logged onto Visual WorkFlo (FileNET
Logon on the Programs/FileNET Panagon Visual Work Flo menu),
then click on the Play button to run your new application.

A form similar to the following now displays:

Running this application without having added code resulted in popula-

tion of the FileNET Visual WorkFlo Work Performer Class List control
with names of the AutoClaim sample’s Work Performer Classes.The
Machine ID, 7, and the number of the isolated region, 900, also display.

3 Stop the application, for now, by closing Form1 with its upper-right-
hand-corner X button.

The Project1 window again displays.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 77

 Client-side Application
Work Administration

Access the help system.

Click once on a control window, then press F1 to access Visual Work-

Flo/RAD online help.

Trap errors by adding code to each control.

1 Double-click with the left-hand mouse button in the Work Performer

Class List control window.

Visual WorkFlo/RAD code that supports this control displays in the

Project1-Form1(Code) window. This is where the developer adds code
to enhance the application.

The two lines of procedure code that display support the Refresh
method, a method shared by all of the RAD controls, which updates a
control’s data, retrieves data associated with the control in the data-
base, and immediately displays the data.

2 In the upper-right corner listbox (Procedures listbox), scroll to select

the VWError procedure:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 78

 Client-side Application
Work Administration

The Project1-Form1 (Code) window now displays code for two proce-
dures: Refresh and VWError. The two lines of error code display as fol-
lows:

Private Sub FNVWRUNWorkPerfClassList1_VWError(ByVal ErrorType As Long, ByVal _

ErrorCode As Long)

End Sub

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 79

 Client-side Application
Work Administration

3 Between the above two lines of code, displayed for the VWError proce-
dure, key in the following code:

ErrorMessages=FNVWRUNWorkPerfClassList1.CompletionStatusList
If UBound(ErrorMessages) >= LBound(ErrorMessages) Then
MsgBox (“FNVWRUNWorkPerfClassList1_VWError” & Chr$(13) & “ErrorType:” _
& ErrorType & Chr$(13) & “ErrorCode:” & ErrorCode & Chr$(13) & _
“CompletionStatusList ErrorMessage:” & Chr$(13) & _
ErrorMessages(UBound(ErrorMessages)))
End If

Adding this code causes Visual WorkFlo to write an error message to a

control’s CompletionStatusList property if an error occurs during exe-
cution of the control. Upon error, the system passes the following to the
VWError event:

• ErrorType

These are the categories of ErrorType:

0 Unknown
1 Control-specific
2 VW_API
3 Common
4 OLE exception
5 OLE display exception

• ErrorCode

Each control has code in its own VWError event that displays the Error-
Type and ErrorCode and checks the CompletionStatusList for mes-
sages.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 80

 Client-side Application
Work Administration

The user can then check the CompletionStatusList to read the text of
the error message.

Tips A space followed by an underscore at the end of a line of code indi-

cates that the line of code is unbroken there (there is no Enter key
used at that point). This Visual Basic convention is for your displaying
convenience and you may locate it differently than shown in the above
sample.

Place an empty space on each side of the & character.

The CompletionStatusList property is of variant data type.

4 Repeat steps 1-3 for the FileNET VW Machine ID Indicator and the
FileNET VW Isolated Region Indicator controls, substituting
MachineID1 and IsolatedRegion1, respectively, for
WorkPerfClassList1.

Tip At step 3, copy the added code from one and paste it into the other,
substituting the control-specific information.

5 Save your form, by clicking on the diskette (Save) icon, as:

rad1.frm

The Save Project As dialog box displays.

6 Save your project, naming it:

RAD.vbp

Later, we will see the result of adding the error trapping code.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 81

 Client-side Application
Work Administration

Tip Should you need to suspend your work on rad1.frm and log off of Vi-
sual WorkFlo and Visual Basic, return to work on the form by logging
back on, then selecting:

• The RAD.vbp file from the Existing projects tab

• Project Explorer from the View menu

• The rad1.frm from the Forms folder

Use the CompletionStatusList property to check logon status:

Visual WorkFlo automatically populates the following FileNET VW con-

trols:

Work Performer Class List

Work Class List

So, if an API call fails while the application loads, neither of the above
cause a VWError event. However, each writes to its own Completion-
StatusList property in such an event. So, you can check the text mes-
sage in that property to see logon status.

1 Click on the Work Performer Class List control window to select it, then
press the F1 key.

The FileNet VW Work Performer Class List Control help page displays.
Note that this control has properties, methods, and events (as do all of
the controls).

2 Click the box to the left of Properties.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 82

 Client-side Application
Work Administration

A help page displays links to lists of properties this control shares with
other Visual WorkFlo/RAD controls.

3 Click the Common Control Properties link.

The Common Control Properties help page displays.

4 Click the CompletionStatusList link.

Description of the CompletionStatusList property displays.

5 While still on the step 4 description page, click the box to the left ot
Events, then the CommonControlEvents link.

The Common Control Events help page displays links to description of

events the controls share, one of which is VWError, which we used in
the previous set of procedures.

6 Close the help pages and return to your Form1 work, where the Work
Performer Class List control is still selected.

7 Double-click the control window.

The control’s code window displays.

8 Select Form from the upper-left listbox:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 83

 Client-side Application
Work Administration

The upper-right listbox automatically displays the procedure name,

Load, and the following two lines of Form_Load procedure code ap-
pear in the code window:

Private Sub Form_Load( )

End Sub

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 84

 Client-side Application
Work Administration

9 Enter the following code between the lines of code displayed in step 8
(copy the code you added to the VW_Error procedure, then edit it):

‘Check for a sucessful logon API call to an IMS server.

ErrorMessages=FNVWRUNWorkPerfClassList1.CompletionStatusList
‘If there is an entry in the CompletionStatusList, display it.
If UBound(ErrorMessages) >= LBound(ErrorMessages) Then
MsgBox (“FNVWRUNWorkPerfClassList1 Control” & Chr$(13) & Chr$(13) & _
“CompletionStatusList ErrorMessage:” & Chr$(13) & Chr$(13) _
& ErrorMessages(UBound(ErrorMessages)))
End If

Addition of this code to the Form_Load procedure for the Work Per-
former Class List and Work Class List controls causes Visual WorkFlo
to check for an error message in the CompletionStatusList. If an API
call fails while the application is loading, the above code causes Visual
WorkFlo to display the message that is in the CompletionStatusList.

10 Close the code window.

Your rad1.frm work again displays.

Further develop the adjustor’s IN basket application:

Add a RAD control that lists Work Objects .

1 From the Project menu, select Components.

2 In the Controls tab of the Components window, click in the checkbox to

the left of the FileNET Visual WorkFlo Work Object List by Work Per-
former Class (Work Obj List By WP Class) control.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 85

 Client-side Application
Work Administration

Tip Leave checked those controls that are already checked.

3 Click OK.

4 Click the control icon (you just added to the toolbox) once, move the
cursor onto Form1, and draw a square with it where you want the con-
trol to appear, using the “Adjustor’s IN Basket Application” on page 73
as a model for sizing and positioning.

5 Enter error-trapping code, beginning with Step 1 on page 78 for guide-

lines.

6 Run the application.

Note that Visual WorkFlo populates all but the RAD control you added
in step 4.

Populate the control list.

The adjustor will want to select one or more Work Performer Class
names (now displayed in the Work Performer Class List control win-
dow) and see a list of Work Objects associated with those Work Per-
former Classes displayed in the Work Obj List By WP Class window
you just added. (If you click on one of the Work Performer Class names
at this point, the Work Object list remains blank, you get an error, and
code displays; you have to end the program and close the code win-
dow to return to work on your rad1.frm).

Add code to the Work Performer Class List control that gives it a proce-
dure to follow when the adjustor makes or changes a selection in its
list:

Place a valid Work Performer Class name in the ClassName property

of the FileNET VW Work Object List by Work Performer Class control.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 86

 Client-side Application
Work Administration

1 End the application if you have been running it.

This displays your rad1.frm work.

2 Double-click the FileNET VW Work Performer Class control window to

display its code window, then select the SelectionChanged procedure
from the upper-right listbox.

3 Between the two lines that display, enter code so that the result looks
like the following:

Private Sub FNVWRUNWorkPerfClassList1_SelectionChanged( )

Dim ClassNames As Variant
ClassNames=FNVWRUNWorkPerfClassList1.SelectedItems
If UBound(ClassNames) <> -1 Then
FNVWRUNWorkObjListByWPClass1.ClassName=ClassNames(0)
FNVWRUNWorkObjListByWPClass1.Refresh
End If
End Sub

Now, when the adjustor selects a Work Performer Class from the list,
here is what happens:

• The SelectionChanged event of the Work Performer Class List con-

trol occurs and Visual WorkFlo executes the above procedure.

• The selected names go into the SelectedItems array, a property of

the Work Performer Class List control.

The data type of this array is Variant.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 87

 Client-side Application
Work Administration

• The names in the SelectedItems property become the value of

ClassNames.

• If the Work Performer Class names in ClassNames are valid, Vi-

sual WorkFlo assigns each name, as an element, to the Class-
Names array, a property of the Work Object List by Work Performer
Class control.

The first name in the SelectedItems array is element zero, so the

first element in the ClassNames property of the Work Object List by
Work Performer Class is now the first Work Performer Class the
adjustor selects.

• Names of Work Objects in the selected Work Performer Class(es)

display in the Work Object List by Work Performer Class control.

4 Run the application again.

5 In the Work Performer Class List control, scroll to and click Mainframe-
Activities.

The Work Objects you created, starting with Step 1 on page 71, are
still associated with the MainframeActivities Work Performer Class.
The names of these Work Objects now populate the Work Object List
by Work Performer Class control window; they and their lock status dis-
play there.

6 End the application.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 88

 Client-side Application
Work Administration

Further develop the adjustor’s IN basket application:

Add a RAD control that lists the values of fields in a Work Object
and locks the Work Object.

1 From the Project menu, select Components.

2 In the Controls tab of the Components window, click in the checkbox to

the left of the FileNET Visual WorkFlo Field Values List.

Leave checked those controls that are already checked and click OK.

3 Click the control icon (you just added to the toolbox) once, move the
cursor onto Form1, and draw a square with it where you want the con-
trol to appear, using the “Adjustor’s IN Basket Application” on page 73
as a model for sizing and positioning.

4 Enter error-trapping code, beginning with Step 1 on page 78 for guide-

lines.

5 Double-click the FileNET VW Work Obj List By WP Class control win-

dow to display its code window, then select the SelectionChanged pro-
cedure from the upper-right listbox.

The adjustor will use your application to see a list of values in a Work
Object’s fields, first selecting the Work Object from the populated Work
Object List by Work Performer Class. So, add code to this control’s Se-
lectionChanged procedure to tell Visual WorkFlo what to do when the
selection is made (what to do upon the SelectionChanged event).

6 Between the two lines that display, enter code so that the result looks
like the following:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 89

 Client-side Application
Work Administration

Private Sub FNVWRUNWorkObjListByWPClass1_SelectionChanged( )

Dim OperationHandles As Variant
‘Lock the current selection and get its locked ID.
OperationHandles=FNVWRUNWorkObjListByWPClass1.SelectedLockedOperationIds
If UBound(OperationHandles) > =LBound(OperationHandles) Then
FNVWRUNFieldValuesList1.VWHandle=OperationHandles(0)
FNVWRUNFieldValuesList1.Refresh
End If
End Sub

Now, when the adjustor selects a Work Object from the list, here is
what happens:

• The SelectionChanged event of the Work Object List by Work Per-

former control occurs and Visual WorkFlo executes the above pro-
cedure.

The SelectionChanged event occurs when the selection status

(Selected or Not Selected) of an item changes. It occurs twice
when the adjustor selects a Work Object: once when the current
selection is de-selected and again on selection of the Work Object.
If the adjustor selects no Work Object, an array with no elements
returns.

• The name of each selected Work Object goes into an element of

the SelectedLockedOperationIds array, a property of the Work Ob-
ject List by Work Performer control.

The data type of this array is Variant.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 90

 Client-side Application
Work Administration

• The names in the SelectedLockedOperationIds property become

the value of OperationHandles.

• If the Work Object names in OperationHandles are valid, Visual

WorkFlo assigns each name, as an element, to the VWHandle ar-
ray, a property of the Field Values List control.

The first name in the SelectedLockedOperationIds array is element

zero, so the first element in the VWHandle property of the Field
Valuse List is now the first Work Object name the adjustor selects.

Population of the FileNET VW Field Values List requires that the

VWHandle property of this control contain one of the following:

Array is this property of

Work Obj List By WP Value in Field Val-
Element of this array Class control ues List
OperationHandle OperationHandles SelectedLockedOpera- Work Performer
tionIds Operation parame-
Identifies the locked Work Ob- ters
ject on which the calling Work
Performer is to perform the cur-
rent Operation

WobAccessHandle WobAccessHandles SelectedAccessHandles Work Object fields

Identifies a Work Object, the

lock status of which depends on
the status of the Locked param-
eter of the SelectedAccessHan-
dles property

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 91

 Client-side Application
Work Administration

WorkObjectHandle WorkObjectHandles SelectedQueueElemen- Exposed Work

tHandles Queue fields
Identifies a Work Object in a
queue during a browse session

WorkPerformerHandle Not applicable Not applicable Work Performer

Class fields
Identifies a Work Queue

Returns from a call to one of

these APIs:
VW_ReportToWork
VW_GetWork
PerformerHandle

• Values of the fields of the selected Work Object(s) display in the

Field Values List control.

In the case of the code we added, the field values to be displayed

are Work Performer Operation parameters because the adjustor
will want the application to set a value into a Work Object field (into
a Work Performer Operation parameter) to complete an Operation.

7 Run the application.

8 From the Work Performer Class List, click on the name of a Work Per-
former that contains Work Objects (MainframeActivities).

The Work Objects in the MainframeActivities Work Performer Class

display in the Work Object List By Work Performer Class control win-
dow. LockStatus for each displays as Not Locked.

9 Click on one of the Work Object names.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 92

 Client-side Application
Work Administration

Visual WorkFlo populates the Field Values List with the Work Object’s
field values and changes the Work Object’s LockStatus to Locked by
<Machine ID>.

10 Click another Work Object name.

Visual WorkFlo populates the Field Values List with this Work Object’s
field values and changes the Work Object’s LockStatus to Locked by
<Machine ID>. The Field Values List now displays the fields of this
Work Object, only, but LockStatus now displays as locked for both
Work Objects.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 93

 Client-side Application
Work Administration

11 Click another Work Performer Class name.

An error displays (because of the locked Work Objects).

12 In the Work Performer Class List control, scroll to and click Mainframe-
Activities.

The Work Objects you created, starting with Step 1 on page 71, are
still associated with the MainframeActivities Work Performer Class.
The names of these Work Objects now populate the Work Object List
by Work Performer Class control window; they and their lock status dis-
play there.

13 End the application.

Unlock a Work Object.

In step 11, above, an error displayed when we tried to select another

Work Performer Class because there were locked Work Objects in the
currently selected Work Performer Class. Because we locked these
with the current run of this application, we can also unlock them with it.
(Had they been locked by another application, this would not be the
case.)

1 Enter code at the top of the SelectionChanged( ) procedure of the

FNVWRUNWorkObjListByWPClass1 control so that the result is as fol-
lows:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 94

 Client-side Application
Work Administration

Private Sub FNVWRUNWorkObjListByWPClass1_SelectionChanged( )

‘Make sure there is nothing locked in the Work Object list by WPC.
Dim ObjectsFailed As Long
ObjectsFailed=FNVWRUNWorkObjListByWPClass1.UnlockAllCurrentOperations(False)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjListByWPClass1.CompletionStatusList
Call DisplayFailures
End If

Dim OperationHandles As Variant

‘Lock the current selection and get its locked ID.
OperationHandles=FNVWRUNWorkObjListByWPClass1.SelectedLockedOperationIds
If UBound(OperationHandles) > =LBound(OperationHandles) Then
FNVWRUNFieldValuesList1.VWHandle=OperationHandles(0)
FNVWRUNFieldValuesList1.Refresh
End If
End Sub

The additional code causes Visual WorkFlo to unlock all Work Objects
locked by this application and refresh the display before the adjustor
makes another selection. In this adjustor’s IN-basket sample, the appli-
cation identifies a locked Work Object by its OperationHandle, which is
one element in an array of OperationHandles in the SelectedLocked-
OperationIds property of the FileNET VW Work Object List by Work
Performer Class control.

2 Enter code at the top of the SelectionChanged( ) procedure of the

FNVWRUNWorkPerfClassList1 control so that the result is as follows:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 95

 Client-side Application
Work Administration

Private Sub FNVWRUNWorkPerfClassList1_SelectionChanged( )

‘Make sure there is nothing locked in the Work Object list by WPC.
Dim ObjectsFailed As Long
ObjectsFailed=FNVWRUNWorkObjListByWPClass1.UnlockAllCurrentOperations(False)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjListByWPClass1.CompletionStatusList
Call DisplayFailures
End If

Dim OperationHandles As Variant

‘Lock the current selection and get its locked ID.
OperationHandles=FNVWRUNWorkPerfClassList1.SelectedItems
If UBound(OperationHandles) > =LBound(OperationHandles) Then
FNVWRUNFieldValuesList1.VWHandle=OperationHandles(0)
FNVWRUNFieldValuesList1.Refresh
End If
End Sub

The additional code causes Visual WorkFlo to unlock all Work Objects
locked by this application and refresh the display before the adjustor
makes another selection. In this adjustor’s IN-basket sample, the appli-
cation identifies a locked Work Object by its OperationHandle, which is
one element in an array of OperationHandles in the SelectedItems
property of the FileNET VW Work Performer Class List control.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 96

 Client-side Application
Work Administration

Unlocking methods. Description of this unlocking method, Unlock-

AllCurrentOperations, and its alternatives follows:

Method Acts upon

UnLock Currently selected , locked Work Object, identified
by an OperationHandle obtained by the current run
of the application that locked it
Visual WorkFlo unlocks the Work Object while it is in
the Work Queue and invalidates the OperationHan-
dle.
UnlockAllCurrent All locked Work Objects identified by OperationHan-
Operations dles obtained by the current run of the appliation that
locked them
Visual WorkFlo unlocks them while they are in the
Work Queue and invalidates the OperationHandles.
UnLockAndDispatch Currently selected , locked Work Object, identified
by an OperationHandle obtained by the current run
of the application that locked it
Visual WorkFlo unlocks the Work Object, saves
changes in Work Performer Operation parameters,
and disipatches the Work Object to the next Work
Queue, as specified by its Instruction Sheet.
UnLockAndDispatch All locked Work Objects identified by an Operation-
AllCurOps Handles obtained by the current run of the applica-
tion that locked them
Visual WorkFlo unlocks the Work Objects, saves
changes in Work Performer Operation parameters,
and disipatches the Work Objects to the next Work
Queue, as specified by the Instruction Sheet of each.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 97

 Client-side Application
Work Administration

Failure display. The added code calls the DispalyFailures function, as

explained in step 2.

3 Click anywhere on rad1.frm to bring up the code window.

4 In the upper-left list box (Objects list) select General and in the upper-
right list box, select Declarations.

The cursor displays at the top of the code.

5 Key in the following code:

Sub DisplayFailures( )
For i=(UBound(ErrorMessages)-ObjectsFailed+1) To UBound(ErrorMessages)
MsgBox(“This is the DisplayFailures procedure triggered by FailedObjects.” & _
Chr$(13) & Chr$(13) & ErrorMessages(i))
Next i
End Sub

Design to trap errors when methods act on multiple Work Objects.

Various methods of the FileNETVW Work Obj List By WP Class con-

trol, including the unlocking methods of step 1, above, act upon Work
Objects.

When the method completes successfully for all Work Objects, the re-
turn value is zero. If the method fails, the return value is the number of
Work Objects on which it fails. Visual WorkFlo writes failures to the
CompletionStatusList property of the FileNET VW Work Obj List By
WP Class control. The code added in this step causes Visual WorkFlo
to display the entry in the CompletionStatusList for each failed Work
Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 98

 Client-side Application
Work Administration

Involve the Work Performer in administration.

Administering workflow may include launching a Work Performer.

The adjustor will use our sample IN basket application for these admin-
istrative tasks:

• Check the IN basket for work to be done.

• Select work

• Assign work to self or to others

• Review the results of assigning the work

In addition to checking and reporting the status of work the adjustor ac-
cesses work and assigns it for processing, at which point it hands the
work off to a Work Performer application. AutoClaim sample code sup-
ports a queue for each of two Instructions: one for claim assignment,
the other for collateral review.

Though the following steps illustrate the interaction of our administra-

tive application with Work Performers, please see “Work Performance”
on page 145 for detailed information about the Work Performer.

Prepare the form for remaining features:

Use Visual Basic features to do the following (consulting Visual Basic

documentation, if necessary, and using the “Adjustor’s IN Basket Ap-
plication” on page 73 as a model):

• Drag and drop a Command button onto rad1.frm, name it cmdExit,

and change its Caption property to read Exit.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 99

 Client-side Application
Work Administration

• Drag and drop a Command button onto rad1.frm, name it cmdAs-

sign, and change its Caption property to read Assign Claim.

• Drag and drop a Command button onto rad1.frm, name it cmdRe-

view, and change its Caption property to read Review Claim.

• Add the title Adjustor’s IN Basket to rad1.frm.

Select work from the IN basket

and assign it to oneself or to others.

1 Double-click the cmdAssign control button to display its code window,

then key in code so that the result looks like the following:

Private Sub cmdAssign_Click( )

Dim WPObject As Object
Dim Result As Variant
End Sub

The adjustor will list Work Objects and their fields, as we have dis-
cussed in the above procedures, then pull a Work Object from the
Work Queue to assign it to a person or process.

This code is the first step in providing the adjustor access to an active
Work Performer with which to pull the Work Object. The code in this
step:

• Creates a variable and declares it an Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 100

 Client-side Application
Work Administration

• Creates a variable in which to receive the array the passive Work

Performer Operation will return.

2 Add the folloiwng line below the declarations of step 1:

Set WPObject=CreateObject(“AdjAssign.Operations” )

The active Work Performer, in this case, will use OLE Automation (as
an OLE client) and invoke the passive Work Performer AdjustorAssign,
which is an OLE server.

The code in this step creates an instance of the AdjAssign.Operations

object, ensuring that Visual WorkFlo loads the passive Work Performer
(OLE server), AdjusterAssign, into memory and prepares it for the
eventual call to execute. The passive Work Performer pushes work to
the adjustor when there is work in the queue to be processed.

Source code for the work assignment passive Work Performer that the
AutoClaim sample supports is in:

C:\Program Files\FileNet\Vw\Samples\AdjAssign.exe

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 101

 Client-side Application
Work Administration

3 Following the variables declared in step 1, declare the following vari-

ables in which to hold data from the FileNET VW Field Values List:

Dim sClaimNumber As String

Dim sClaimAmount As String
Dim sClaimDate As String
Dim sInsuredsName As String
Dim sIBusinessPhone As String
Dim sStatus As String
Dim sInjury As String
Dim sEstimatorDocsComplete As String
Dim sPhysicianDocsComplete As String

The RetrieveItemValueByName method of the Field Values List control

returns the value of each field as a data element in the array of strings
required by the AdjAssign.Operations object. If the data in the element
is not string information, you must convert it back to its iriginal data
type. If the data is string information, it returns in quotes.

4 Add the following code after the declarations to create a function that
removes quotes from string data before the application passes it to the
AdjAsssign.Operations object:

Function RemoveQuotes(asting As String) As String

RemoveQuotes=Mid$(astring,2,Len(astring)-2)
End Function

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 102

 Client-side Application
Work Administration

5 Before the End Function line of the above RemoveQuotes function add
the following code, which uses the function to evaluate and assign data
returned by the RetrieveItemValueByName method:

sClaimNumber=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimNumber”))
sClaimAmount=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimAmount”))
sClaimDate=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimDate”))
sInsuredsName=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprInsuredsName”))
sIBusinessPhone=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprIBusinessPhone”))
sStatus=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValueByName(“sopr
Status”))
sInjury=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-ByName(“sopr
Injury”))
sEstimatorDocsComplete=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprEstimatorDocsComplete”))
sPhysicianDocsComplete=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprPhysicianDocsComplete”))

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 103

 Client-side Application
Work Administration

6 After the step 5 code, add the following to invoke, pass data to, and re-
ceive data from a passive Work Performer:

‘Invoke WP Operation.
Result =WPObject.ScheduleEstimatorAndMR(sClaimNumber, _
sClaimAmount, _
sClaimDate, _
sInsuredsName, _
sIBusinessPhone
sStatus, _
sInjury, _
sEstimatorDocsComplete, _
sPhysicianDocsComplete)

7 After step 6 code, add the following:

If Result=True Then
ErrorCode=FNVWRUNFieldValuesList1.UpdateItemValueByName(“soprEstimatorDocs
Complete”, Chr(39) & sEstimatorDocsComplete & Chr(39))
ErrorCode=FNVWRUNFieldValuesList1.UpdateItemValueByName(“soprPhysicianDocs
Complete”, Chr(39) & sPhysicianDocsComplete & Chr(39))

This checks to see that the Work Performer Operation was successful,
then updates the Work Performer’s parameters. It replaces single
quotes (Chr(39)) around the string before passing the string back to
the Work Performer Operation parameter.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 104

 Client-side Application
Work Administration

8 After step 7 code, add the folloiwng:

‘Check to see that all unlocked and dispatched Work Objects completed the method.
ObjectsFailed=FNVWRUNWorkObjListByWPClass1.UnlockAndDispatch(False)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjListByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End If
FNVWRUNFieldValuesList1.Clear
cmdAssign.Enabled=False
End Sub

Now that work is finished on the Work Object, this code:

• Unlocks and dispatches the Work Object

If Work Objects fail to complete the UnlockAndDispatch method,

the method returns a count of the number of Work Objects that fail
to the CompletionStatusList property.

• Calls the subroutine, DisplayFailures, which checks the Comple-

tionStatusList property for failures and displays these.

• Clears the Field Values List

The Work Object is dispatched.

• Disables the Assign button

There is no Work Object currently selected.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 105

 Client-side Application
Work Administration

Review the claim.

Code that enables the adjustor to review the claim is similar to that you
added to enable work assignment.

Double-click the cmdReview control button to display its code window,

then key in code so that the result looks like the following:

Private Sub cmdReview_Click( )

‘Invoke an OLE server application to process the Work Object.
Dim WPObject As Object
Dim Result As Variant

‘Call the OLE server.

Set WPObject=CreateObject(“AdjReview.Operations” )

‘Dimension parameters.
Dim iPriority As String
Dim sClaimNumber As String
Dim fClaimAmount As Double
Dim sClaimDate As String
Dim sInsuredsName As String
Dim sIBusinessPhone As String
Dim sStatus As String
Dim sInjury As String
Dim sEstimatorDocsComplete As String
Dim sPhysicianDocsComplete As String

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 106

 Client-side Application
Work Administration

Dim sEstimatorDocInfo As String

Dim sEstimatorDocImages As String
Dim sPhysicianDocInfo As String
Dim sPhysicianDocImages As String

Dim I, J, K As Integer

‘Get values of selected Work Object field values to use as input.

iPriority=CLng(FNVWRUNFieldValuesList1.RetrieveItemValueByName(“ioprPriority”))
sClaimNumber=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimNumber”))
sClaimAmount=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimAmount”))
sClaimDate=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprClaimDate”))
sInsuredsName=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprInsuredsName”))
sIBusinessPhone=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-
ByName(“soprIBusinessPhone”))
sStatus=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValueByName(“sopr
Status”))
sInjury=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItemValue-ByName(“sopr
Injury”))
sEstimatorDocsComplete=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprEstimatorDocsComplete”))

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 107

 Client-side Application
Work Administration

sPhysicianDocsComplete=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprPhysicianDocsComplete”))
sEstimatorDocInfo=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprEstimatorDocInfo”))

’For I=0 To 1
‘ VsEstimatorDocInfo(I)=TsEstimatorDocInfo
‘ MsgBox VsEstimatorDocInfo(I)
‘Next I

sEstimatorDocImages=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprEstimatorDocImages”))

‘For J=0 To 2
‘ VsEstimatorDocImages(J)=sEstimatorDocImages(J)
‘ MsgBox VsEstimatorDocImages(J)
‘Next J

sPhysicianDocInfo=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprPhysicianDocInfo”))

‘For K=0 To 1
‘ VsPhysicianDocInfo(K)=sPhysicianDocInfo(K)
‘ MsgBox VsPhysicianDocInfo(K)
‘Next K

sPhysicianDocImages=RemoveQuotes(FNVWRUNFieldValuesList1.RetrieveItem
ValueByName(“soprPhysicianDocImages”))

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 108

 Client-side Application
Work Administration

For L=0 To 1
‘ VsPhysicianDocImages(L)=sPhysicianDocImages(L)
‘ MsgBox VsPhysicianDocImages(L)
‘Next L

‘Invoke WP Operation
Result =WPObject.ScheduleEstimatorAndMR(sClaimNumber, _
sClaimAmount, _
sClaimDate, _
sInsuredsName, _
sIBusinessPhone
sStatus, _
sInjury, _
sEstimatorDocsComplete, _
sPhysicianDocsComplete, _
sEstimatorDocInfo, _
sEstimatorDocImages, _
sPhysicianDocInfo, _
sPhysicianDocImages)

If Result=True Then
ErrorCode=FNVWRUNFieldValuesList1.UpdateItemValueByName(“soprStatus”, Chr(39)
& sStatus & Chr(39))
ErrorCode=FNVWRUNFieldValuesList1.UpdateItemValueByName(“foprClaimAmount”,
fClaimAmount)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 109

 Client-side Application
Work Administration

Check to see that all unlocked and dispatched Work Objects completed the method.
ObjectsFailed=FNVWRUNWorkObjListByWPClass1.UnlockAndDispatch(False)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjListByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End If
FNVWRUNFieldValuesList1.Clear
cmdReview.Enabled=False
End Sub

The above code creates an instance of the AdjReview.Operations ob-

ject, ensuring that Visual WorkFlo loads the passive Work Performer
(OLE server), AdjustorReview, into memory and prepares it for the
eventual call to execute. The passive Work Performer pushes work to
the adjustor when there is work in the queue to be processed.

Source code for the work review passive Work Performer that the Auto-
Claim sample supports is in:

C:\Program Files\FileNet\Vw\Samples\AdjReview.exe

Customize button activation.

Follow the procedures below so that the Assign Claim and Review
Claim buttons will be active only when Work Objects are selected for
assignment or review.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 110

 Client-side Application
Work Administration

1 In the code window for the FileNET VW Work Performer Class List
control add the following code at the end of the SelectionChanged pro-
cedure:

‘Set Assign and Review buttons to false when adjustor selects a new WP Class.
cmdAssign.Enabled=False
cmdReview.Enabled=False

2 In the code window for the FileNET VW Work Object List by Work Per-
former Class control add the following code at the end of the Selection-
Changed procedure:

‘Enable the cmd button associated with the selected WP Class.

If ClassNames(0)=”AdjustorAssign” Then
cmdAssign.Enabled=True
cmdReview.Enabled=False
ElseIf ClassNames(0)=”AdjustorReview” Then
cmdAssign.Enabled=False
cmdReview.Enabled=True
End If

RAD Controls for General Access Customer Service

Use Visual WorkFlo/RAD Controls to develop an application that tracks
and reports the progress of work.

The following procedures result in an application similiar to “Customer

Service Application” on page 113.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 111

 Client-side Application
Work Administration

The user selects a Work Class to see a list of Work Objects that are in
the Work Class and the contents of the Work Object fields. The appli-
cation also displays the name of the Work Performer Class, Instruction
Sheet, current Operation, and lock status associated with the selected
Work Object.

Tip Review the preceding Adjustor’s IN Basket application development

procedures for a detailed version of many of the following steps.

1 Create a new Visual Basic 5.0 Standard EXE project.

2 From the Project menu, select Components.

3 In the Controls tab, check the box to the left of the following FileNET Vi-
sual WorkFlo/RAD controls:

Current Operation Status

Field Values List
Isolated Region Indicator
Machine ID Indicator
Work Class List
Work Obj List By Wk Class
Work Object Lock Status

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 112

 Client-side Application
Work Administration

Customer Service Application

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 113

 Client-side Application
Work Administration

4 Click OK, placing these controls in the toolbox.

5 Drag and drop the controls onto the form, using the “Customer Service
Application” on page 113, as a guide to size and location of each con-
trol.

Visual WorkFlo automatically populates these FileNET VW\RAD con-

trols:

Isolated Region Indicator

Machine ID Indicator
Work Class List

6 Add labels and an Exit button, as shown.

7 Enter error trapping code in each control, including failures during the
Form_Load event (Visual WorkFlo logon API failure).

8 Enter the following code in the SelectionChanged procedure of the

FileNET VW Work Class List control to assign element zero of its Se-
lectedItems property to the ClassName property of the FileNET VW
Work Object List by Work Class control:

Private Sub FNVWRUNWorkClassList1_SelectionChanged( )

Dim ClassNames As Variant
ClassNames=FNVWRUNWorkClassList1.SelectedItems
If UBound(ClassNames) <> -1 Then
FNVWRUNWorkObjListByWkClass1.ClassName=ClassNames(0)
FNVWRUNWorkObjListByWkClass1.Refresh
End If
End Sub

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 114

 Client-side Application
Work Administration

The SelectionChanged event occurs when the user selects a Work

Class.

The ClassName property must contain a valid Work Class name in or-
der for Visual WorkFlo to populate the Work Object List by Work Class.
When the user selects a Work Class, Visual WorkFlo writes the selec-
tion to the SelectedItems property of the Work Class List control. Each
element of the SelectedItems array (Variant data type) is the name of a
selected Work Class and element zero of the array is the first Work
Class selected.

9 Enter the following code in the SelectionChanged procedure of the

FileNET VW Work Object List by Work Class control:

Private Sub FNVWRUNWorkObjListByWkClassList1_SelectionChanged( )

Dim WobAccessHandles As Variant
Dim WobAccessHandle As Long
Dim QueryCountIndices As Variant
WobAccessHandles=FNVWRUNWorkObjListByWkClass1.SelectedAccessHandles(False)
‘Check for a valid selection.
If UBound(WobAccessHandles) <> -1 Then
FNVWRUNWorkObjListByWkClass1.WobAccessHandle=WobAccessHandles(0)
FNVWRUNWorkObjListByWkClass1.Refresh
End If
End Sub

The SelectedAccessHandles property of this control has a Boolean

parameter called Locked. The application looks at all Work Objects in
the workflow and, if the Locked parameter is set to False, Visual Work-
Flo returns all of the Work Objects. If Locked is set to True, Visual
WorkFlo returns only unlocked Work Objects. If there is a Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 115

 Client-side Application
Work Administration

that has been locked by other means, this application does not display
and it triggers a VWError event.

10 Enter the following code to set the FieldValuesList controls to not edit-
able:

FNVWRUNFieldValuesList1.IsEditable=False
FNVWRUNFieldValuesList2.IsEditable=False
FNVWRUNFieldValuesList3.IsEditable=False
‘Generate the Field Values list.
FNVWRUNFieldValuesList1.VWHandle=WobAccessHandle
FNVWRUNFieldValuesList1.Refresh

11 For each Field Values List control:

• Click on the control window

• From the View menu, select Property Pages (not to be confused

with Properties Window)

• In the Column Headers tab:

• De-select Show Column Headings and Display Data Type

• In Column Info, set the columns you do not want to display to a

width of zero and set those you do want to display to an appropri-
ate width, as illustrated below:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 116

 Client-side Application
Work Administration

12 Add the followng code:

- Assign to an array those fields that are to be displayed

- Display only one field in a second Field Values List

Dim FieldsToDisplay As Variant

ReDim FieldsToDisplay(0) As String
FieldsToDisplay(0)=”swcEstimatorDocsComplete”

13 Add the following code:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 117

 Client-side Application
Work Administration

- Pass the WobAccessHandle to VWHandle

- Pass the FieldsToDisplay array to FieldNames
- Refresh the display

FNVWRUNFieldValuesList2.VWHandle=WobAccessHandle
FNVWRUNFieldValuesList2.FieldNames=FieldsToDisplay
FNVWRUNFieldValuesList2.Refresh

14 Add the followng code to display only one field in a third FieldVal-
uesList:

FieldsToDisplay(0)=”swcPhysicianDocsComplete”
FNVWRUNFieldValuesList3.VWHandle=WobAccessHandle
FNVWRUNFieldValuesList3.FieldNames=FieldsToDisplay
FNVWRUNFieldValuesList3.Refresh

15 Add the followng code to pass the WobAccessHandle of the Work Ob-
ject from the Work Object List by Work Class SelectedAccessHandles
property and to refresh the display.

‘Check the Locked status.

WObjLockStatus1.WorkObject=WobAccessHandle
WObjLockStatus1.Refresh

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 118

 Client-side Application
Work Administration

16 Add the followng code to assign QueryHandle (the Work Class ID) to
the QueryHandle property of the FileNET VW Current Operation Sta-
tus control:

WOCurrOpStatus1.QueryHandle=FNVWRUNWorkObjListByWkClass1.QueryHandle

17 Add the followng code:

QueryCountIndices=FNVWRUNWorkObjListByWPClass1.SelectedQueryCountIndices
If UBound(QueryCountIndices) > =LBound(QueryCountIndices) Then
WOCurrOpStatus1.WorkObject=QueryCountIndices(0)
End If
WOCurrOpStatus1.Refresh
End Sub

RAD Controls for Management Access and Reports

Use Visual WorkFlo/RAD Controls to develop an application that pro-
vides a manager the status of work in queues. The following proce-
dures result in an application similiar to “Manager’s Application” on
page 121.

18 In the Controls tab, check the box to the left of the following FileNET Vi-
sual WorkFlo/RAD controls:

Isolated Region Indicator

Machine ID Indicator
Queue Depth Graph

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 119

 Client-side Application
Work Administration

Work Performer Class List

Work Obj List By WP Class

Click OK, placing these controls in the toolbox.

19 Drag and drop onto the form:

Controls in step 3
Eight command buttons
One text box

Use the “Manager’s Application” on page 121 as a guide to size and lo-
cation of each item.

20 Enter error trapping code in each control, including failures during the
Form_Load event (Visual WorkFlo logon API failure).

21 Enter error trapping code for possible multiple Work Object failure.

See details in Step 5 on page 98. (Note this page’s number, so that
you may easily return to it.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 120

 Client-side Application
Work Administration

Manager’s Application

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 121

 Client-side Application
Work Administration

Display queue depth graphically.

The FileNET VW Queue Depth Graph control graphically represents

the number of Work Objects in a Work Performer Class queue that are
to be processed. The graph is a bar chart, a line graph, or a pie chart
(click on this control’s window, then press F1 to link to sample graphs
in Visual WorkFlo/RAD help).

1 Enter code in the Click procedure of the Update Graph button, as fol-
lows:

Private Sub cmdUpdateGraph_Click( )

Dim WPClassNames As Variant
Dim WPClassName As Variant
Dim Success As Boolean
FNVWRUNQueueDepth1.Clear

This begins the code that populates the Queue Depth Graph and
clears previous entries. Using a Click, rather than a SelectionChanged,
event holds execution of the code until the manager has selected all
Work Performer Classes of interest.

2 Add the following code:

WPClassNames=FNVWRUNWorkPerfClassList1.SelectedItems

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 122

 Client-side Application
Work Administration

3 For each Work Performer Class name in WPClassNames add:

Success=FNVWRUNQueueDepth1.AddWPClass(WPClassName, -1, 10)

If Success=False Then
MsgBox (“FNVWRUNQueueDepth1.AddWPClass failed for the _
Work Performer Class” & WPClassName)
End If
Next
End Sub

The AddWPClass method of the Queue Depth control adds Work Per-
former Classes and watermark thresholds to a graph; the RemoveWP-
Class method removes these. The above code adds a selected Work
Performer Class name, refreshes the graph, adds the next selected
Work Performer Class name, refreshes the graph, etc. This method’s
parameters are WPClassName, LowWaterThreshold, and HighWater-
Threshold (WPClassName, -1, and 10, respectively, in the above
code).

The sample uses -1 to show that it requires no low-threshold water-

mark. A developer can use the Queue Depth control’s LowWaterAlarm
and HighWaterAlarm events to signal the manager when the number
of Work Objects in a queue has exceeded one of the watermarks.

The AddWPClass and RemoveWPClass methods return a Boolean—

True if successful, False if unsuccessful.

Tip Click once in the Queue Depth control window, then press F1, to re-
view online help regarding the AddWPClass and RemoveWPClass
methods, thresholds, and alarms.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 123

 Client-side Application
Work Administration

Sequentially display Work Objects

in multiple Work Performer Classes.

1 Add the following code to the Click procedure of the Apply to Work Ob-
ject List command button:

Private Sub cmdApplyToWorkObjectList_Click( )

ClassNames=FNVWRUNWorkPerfClassList1.SelectedItems
‘Check for a valid element before assigning and refreshing.
If UBound(ClassNames) > =LBound(ClassNames) Then
i=LBound(ClassNames)
FNVWRUNWorkObjListByWPClass1.ClassName=ClassNames(i)
txtWorkPerformerClass.Text=ClassNames(i)
FNVWRUNWorkObjListByWPClass1.Refresh
If UBound(ClassNames) > LBound(ClassNames) Then cmdNextQueue.Enabled=True
End If
End Sub

The code in this step:

• Displays the Work Objects of each selected Work Performer Class

Placing it in a button click event holds execution of the code until

the manager has selected all Work Performer Classes of interest.

• Assigns the current selection to a text box

• Enables the Next Work Queue button, if there is more than one se-
lection

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 124

 Client-side Application
Work Administration

2 Add the following code to the same click procedure to disable the Next
Work Queue button when the manager selects another Work Per-
former Class:

Private Sub FNVWRUNWorkPerfClassList1_SelectionChanged( )

cmdNextQueue.Enabled=False
End Sub

Unlock selected Work Objects.

Add the following code to the Click procedure of the Unlock Selected
Item command button:

Private Sub cmdUnlockSelectedItem_Click( )

ObjectsFailed=FNVWRUNWorkObjByWPClass1.Unlock(True)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End Sub

The Unlock method in the above code acts only upon a selected Work
Object that the current instance of the application locked. The code un-
locks Work Objects while they are in the queue and the Unlock method
returns a value that is the number of Work Objects that failed to un-
lock.. If the value of the Unlock method’s ConfirmAction parameter is
true, the code displays a “Yes/No” dialog box that asks for confirmation
of an action to be taken in response to this.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 125

 Client-side Application
Work Administration

Lock Operations that are associated

with selected Work Objects.

Add the following code to the Click procedure of the Lock Selected Op-
eration command button:

Private Sub cmdLockSelectedOperation_Click( )

ObjectsFailed=FNVWRUNWorkObjByWPClass1.Lock(True)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End Sub

The Lock method in the above code locks the Work Performer Opera-
tion associated with a selected Work Object. It returns a value that is
the number of Work Objects that failed to lock.. If the value of the Lock
method’s ConfirmAction parameter is true, the code displays a “Yes/
No” dialog box that asks for confirmation of an action to be taken in re-
sponse to this.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 126

 Client-side Application
Work Administration

Dispatch selected Work Objects.

Add the following code to the Click procedure of the Dispatch Selected
Item command button:

Private Sub cmdDispatchSelectedItem_Click( )

ObjectsFailed=FNVWRUNWorkObjByWPClass1.UnlockAndDispatch(True)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End Sub

The UnlockAndDispatch method in the above code acts only upon a

selected Work Object that the current instance of the application
locked. The code unlocks a Work Object, saves changes made in the
Operation parameters, and dispatches the Work Object to the next
Work Queue specified by the Instruction Sheet.

The UnLock method returns a value that is the number of Work Ob-
jects that failed to unlock.. If the value of the UnLock method’s Confir-
mAction parameter is true, the code displays a “Yes/No” dialog box that
asks for confirmation of an action to be taken in response to this.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 127

 Client-side Application
Work Administration

Terminate selected Work Objects.

Add the following code to the Click procedure of the Terminate Se-
lected Item command button:

Private Sub cmdTerminateSelectedItem_Click( )

ObjectsFailed=FNVWRUNWorkObjByWPClass1.Terminate(True)
If ObjectsFailed<>0 Then
ErrorMessages=FNVWRUNWorkObjByWPClass1.CompletionStatusList
Call DisplayFailures
End If
End Sub

The Terminate method in the above code terminates the specified

Work Objects, which call the Terminate Instuction Sheet before they
terminate.

The Terminate method returns a value that is the number of Work Ob-
jects that failed to unlock.. If the value of the method’s ConfirmAction
parameter is true, the code displays a “Yes/No” dialog box that asks for
confirmation of an action to be taken in response to this.

Administrative Calls to the API

An alternative to using VisualWorkFlo/RAD controls is to design the
administrative application to call APIs (in the sequence shown by the
green path in “API Calling Sequence” on page 484).

Explore an AutoClaim sample customer inquiry application by running

Visual Basic and opening the following project, which is in the directory
where you installed Visual WorkFlo:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 128

 Client-side Application
Work Administration

Samples\Source Code\CustInquiry.vbp

A form, such as that on the following page, displays. (This figure dis-
plays data in the form’s fields for illustration.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 129

 Client-side Application
Work Administration

AutoSure’s agent receives a call from a customer, who wants to know

the status of a claim. Sample application code in this section enables
the agent to:

• Use the claimant’s name to query the system, to see whether there
is a claim in progress for the claimant (query a roster for a Work
Object by Work Class and Work Object ID)

• Query the log for records, based on the claimant’s name or on the
claim number, if the roster query results in no match (indicating that
the claim is no longer in the workflow)

In the Customer Inquiry form, the agent enters the claimant’s name in
the Name of Insured field. In Visual Basic, view the source code of the
CustInquiry.vbp project to see the subroutine, cmdQuery_Click( ),
which launches when the agent then clicks Query.

The following sample code enables the agent to complete the five
steps above.

Sample Roster Query

Before querying for log records on a Work Object, the agent in our ex-
ample queries the roster to see whether there is a Work Object in the
workflow that is associated with the claimant’s name. If there is none,
the agent can make a log query by claimant name to retrieve records
on the Work Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 130

 Client-side Application
Work Administration

The developer uses administrative application code, following the

steps below, to make a roster query and determine whether the Work
Object of interest—an auto insurance claim in this case—is in process
and, if so, to retrieve the claim number. The application uses the follow-
ing in searching through the roster:

• Name of the Work Class to which the Work Object belongs

• Work Object’s Work Object ID

See “Work Object Identification” on page 52 to compare the Work

Object ID, used in a roster query, with various other forms of Work
Object identification.

Once Visual WorkFlo finds the Work Object, it retrieves the claim num-
ber from the Work Object’s claim number field.

This code includes calls the following APIs:

“VW_WobQueryCreate” on page 463

“VW_SetString” on page 454

“VW_WobQueryExecute” on page 469

“VW_WobQueryGetAccessHandle” on page 472

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 131

 Client-side Application
Work Administration

“VW_GetString” on page 348

“VW_FreeAccessHandle” on page 300

“VW_WobQueryEnd” on page 468

1 Make the subroutine public and declare the variables:

Public Sub PerformWobQuery (ByVal WorkClassName As

String, ByVal WobID As String)

Dim LockForUpdate As Long

Dim WobQueryHandle As Long
Dim WobAccessHandle As Long
Dim QueryCountLimit As Long
Dim QueryCount As Long
Dim QueryIndex As Long
Dim FieldNames As Variant

Dim AssignedPhysician As String

Dim AssignedEstimator As String
Dim ClaimNumber As String

2 Set the system to not lock the Work Object to the developer’s worksta-
tion, by setting LockForUpdate to false.

LockForUpdate = 0

3 Begin a query in the Work Class of the Work Object of interest, identi-
fying this Work Class in WorkClassName.

Call check (VWServer.VW_WobQueryCreate

(LogonHandle,
WorkClassName,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 132

 Client-side Application
Work Administration

WobQueryHandle),
“VW_WobQueryCreate”)

4 Limit the query to finding a single Work Object, rather than listing all of
the Work Objects in a Work Class:

Call check (VWServer.VW_SetString

(WobQueryHandle,
"",
WobID),
“VW_SetString”)

Provide an empty string in the FieldName input parameter. Provide the

Work Object ID in the Value input parameter.

See the diagram “Access specific Work Objects in a Work Class” on

page 465 for explanation of the API relationship in this step of the
query.

5 Match and count the Work Objects that meet the Work Class name
and Work Object ID criteria—now in WobQueryHandle:

QueryCountLimit = 0

Call check (VWServer.VW_WobQueryExecute

(WobQueryHandle,
0,
QueryCount),
“VW_WobQueryExecute”)

Developer input of zero (0) in the QueryCountLimit parameter, above,

returns in QueryCount the number of all Work Objects in the Work
Class identified by WobQueryHandle, to which the API calls in steps 3
and 4 contributed.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 133

 Client-side Application
Work Administration

Each Work Object matched and counted now has a batch index (a
QueryCountIndex). Select the Work Object of interest and use its Que-
ryCountIndex as input in step 6 code.

6 If there is no match:
Skip the remaining steps of the roster query and begin a log
query (because the Work Object is not in the workflow, but you may
find a record of it in the log if it has already been processed.) See
“Sample Log Query” on page 135.

If there is a match:
Access the Work Object by identifying it with its QueryCountIndex (as
generated in step 5) and locking it to the developer’s workstation by
setting LockForUpdate to true.

For QueryCountIndex = 0 To QueryCount - 1

Call check (VWServer.VW_WobQueryGetAccessHandle

(WobQueryHandle,
QueryCountIndex,
LockForUpdate,
WobAccessHandle),
“VW_WobQueryGetAccessHandle”)

7 Get the claim number from the Work Object:

Call check (VWServer.VW_GetString

(WobAccessHandle,
“swcClaimNumber”,
ClaimNumber),
“VW_GetString”)
txtClaimNumber.Text = ClaimNumber

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 134

 Client-side Application
Work Administration

In the above call, the developer inputs “swcClaimNumber” to the

FieldName parameter and the API returns the claim number contained
in the Work Object’s swcClaimNumber data field. The claim number re-
turns in the output parameter ClaimNumber (represented by Value in
the API detail).

8 Free the resources allocated for the query in steps 3 and 6:

Call check (VWServer.VW_FreeAccessHandle

(WobQueryHandle, 0, 0, "“),
“VW_FreeAccessHandle”)

Next QueryIndex
Call check (VWServer.VW_WobQueryEnd(WobQueryHandle),
“VW_WobQueryEnd”)

Sample Log Query

After making a roster query and finding that the Work Object of interest
is not in process, an agent makes a log query to see whether there are
event records on the Work Object. The agent queries on a claimant
name or claim number to retrieve records on the Work Object, which
has apparently been processed and paid.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 135

 Client-side Application
Work Administration

The AutoSure developer uses the sample administrative application

code, following the steps below, to make a log query on a claimant
name or a claim number. In doing this, the user can determine which
Operations Visual WorkFlo completed on the claim (the Work Object).

This code includes calls to the following APIs:

“VW_QsCreateQuerySpecifier” on page 403

“VW_GetErrorMessage” on page 324

“VW_LogQueryBegin” on page 381

“VW_LogQueryNextRecords” on page 384

“VW_LogQueryEnd” on page 383

1 Make the subroutine public:

Public Sub PerformLogQuery (ByVal WobTag As String)

If you had no match in step 5 of the roster query, you also had no Work
Object from which to retrieve a claim number. In this case, make a log
query that searches for the claimant’s name to determine whether
there is a record of the Work Object. (If processing of the Work Object
is already complete, there are log records on it.)

In the above line of code, WobTag represents either the name or the
claim number on which your application is to query the log.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 136

 2 Declare variables:

Dim LogonHandle As Long

Dim LogQueryHandle As Long
Dim MaximumRecordsToRead As Long
Dim LogRecords As Variant
Dim Done As Integer
Dim NumberRead As Long
Dim QuerySpecifierIndexKey As String
Dim QuerySpecifierHandle As Long
Dim QuerySpecifierMinimumValues As Variant
Dim QuerySpecifierMinimumEqual As Integer
Dim QuerySpecifierMaximumValues As Variant
Dim QuerySpecifierMaximumEqual As Integer
Dim QuerySpecifierFilter As String
Dim QuerySpecifierFilterSubstitutionVariables
As Variant
Dim errorError As Long
Dim errorCode As Long
Dim errMsg As Long

3 Initialize variables:

QuerySpecifierIndexKey = “F_LogWobTag”

QuerySpecifierMinimumValues = Array(WobTag)
QuerySpecifierMinimumEqual = 1
QuerySpecifierMaximumValues = Array(WobTag)
QuerySpecifierMaximumEqual = 1

Input of F_LogWobTag to the QuerySpecifierIndexKey parameter, be-

low, returns a query specifier that the application subsequently uses in

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 137

 a log query on a Work Object. The Work Object tag of the Work Object,
F_WorkObjectTag, is an element of the system-defined index key, the
array F_LogWobTag. (Compare this to input of the system-defined in-
dex key, F_LogTime, which would return a query specifier to use in a
subsequent log query over a period.)

4 Create a query specifier, using the input parameters to limit the query
to records of interest:

errorCode = VWServer.VW_QsCreateQuerySpecifier
(LogonHandle,
QuerySpecifierHandle,
QuerySpecifierIndexKey,
QuerySpecifierMinimumValues,
QuerySpecifierMinimumEqual,
QuerySpecifierMaximumValues,
QuerySpecifierMaximumEqual,
QuerySpecifierFilter,
QuerySpecifierFilterSubstitutionVariables)
If (errorCode <> 0) Then
errorError = VWServer.VW_GetErrorMessage
(errorCode, errMsg)
MsgBox Str$ (errorCode) & “, “ & errMsg
End if

5 Start the query :

Call check (VWServer.VW_LogQueryBegin

(LogonHandle,
QuerySpecifierHandle,
LogQueryHandle),
“VW_LogQueryBegin”)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 138

 This API uses the query specifier, QuerySpecifierHandle, produced in
step 4, to access the log.

6 Retrieve records, specifying how many to retrieve at a time, up to a

maximum number of records (up to one hundred records in this exam-
ple):

MaximumRecordsToRead = 100
Done = 0

Call check (VWServer.VW_LogQueryNextRecords

(LogQueryHandle,
MaximumRecordsToRead,
LogRecords,
Done),
“VW_LogQueryNextRecords”)

If UBound(LogRecords) > LBound(Log Records) Then

For i = 0 To UBound(LogRecords)
Call ParseLogEntry(LogRecofds(i))
Next i
End if

7 Free resources allocated for the query in step 4:

Call check (VWServer.VW_LogQueryEnd

(LogQueryHandle),
“VW_LogQueryEnd”)

Sample Queue Query

Typical steps of a queue query are:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 139

 Setup

Obtaining a list of indexes

Obtaining a list of fields

Querying the queue

Using queue query entry points

Using an index range

Using a filter and substitution variables

An example of queue query usefulness is query a list of Work Objects

that are assigned be the Operations of a specific Work Performer.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 140

 A queue query includes calls to the following APIs:

“VW_QsCreateQuerySpecifier” on page 403

“VW_GetErrorMessage” on page 324

“VW_QQueryBegin” on page 390

“VW_QQueryNextLockedWorkObject” on page 399

“VW_QQueryNextWorkObject” on page 401

one of the set data APIs--see “Set Data” on page 492 for choices]

one of the get data APIs--see “Get Data” on page 494 for choices]

“VW_LockWorkObject” on page 367

“VW_UnlockAndDispatch” on page 461

“VW_QQueryEnd” on page 398

See “Queue Query API Calling Sequence” on page 392 for the rela-
tionship of queue query APIs.

1 Make the subroutine public:

Public Sub PerformQueueQuery (ByVal WobTag As

String)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 141

 WobTag represents either the name or the claim number on which your
application is to query the queue.

2 Declare variables:

Dim LogonHandle As Long

Dim QueueQueryHandle As Long
Dim QueueElementHandle As Long
Dim QueueName As String
Dim QueueQueryOptions As Long
Dim BatchSize As Long
Dim OperationHandle As Long
Dim QuerySpecifierIndexKey As String
Dim QuerySpecifierHandle As Long
Dim QuerySpecifierMinimumValues As Variant
Dim QuerySpecifierMinimumEqual As Integer
Dim QuerySpecifierMaximumValues As Variant
Dim QuerySpecifierMaximumEqual As Integer
Dim QuerySpecifierFilter As String
Dim QuerySpecifierFilterSubstitutionVariables
As Variant
Dim errorError As Long
Dim errorCode As Long
Dim errMsg As Long

3 Initialize variables:

QuerySpecifierIndexKey = F_WobNum

QuerySpecifierMinimumValues = Array(WobTag)
QuerySpecifierMinimumEqual = 1
QuerySpecifierMaximumValues = Array(WobTag)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 142

 QuerySpecifierMaximumEqual = 1
[QuerySpecifierFilter = ]
[QuerySpecifierFilterSubstitutionVariables = ]

4 Create a query specifier, using the input parameters to limit the query
to records of interest:

errorCode = VWServer.VW_QsCreateQuerySpecifier
(LogonHandle,
QuerySpecifierHandle,
QuerySpecifierIndexKey,
QuerySpecifierMinimumValues,
QuerySpecifierMinimumEqual,
QuerySpecifierMaximumValues,
QuerySpecifierMaximumEqual,
QuerySpecifierFilter,
QuerySpecifierFilterSubstitutionVariables)
If (errorCode <> 0) Then
errorError = VWServer.VW_GetErrorMessage
(errorCode, errMsg)
MsgBox Str$ (errorCode) & “, “ & errMsg
End if

5 Start the query :

Call check (VWServer.VW_QQueryBegin

(QuerySpecifierHandle,
QueueName,
0 x 1,
40,
QueueQueryHandle),
“VW_QQueryBegin”)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 143

 This API uses the query specifier, QuerySpecifierHandle, produced in
step 4, to limit query of the queue the developer names in the Queue-
Name parameter to filtered Work Objects within a range of key index
values.

Developer input of 0 x 1 in the QueueQueryOptions parameter speci-

fies VW_QQ_READ_LOCKED, which means that the subsequent
query will read the data fields of both locked and unlocked Work Ob-
jects. Since the developer does not specify 0 x 8, VW_QQ_WANT_
TO_LOCK, the next API call is to VW_QQueryNextWork Object( ),
rather than to VW_QQueryNextLockedWorkObject( ).

The developer specifies a batch size of 40 Work Objects in the Batch-

Size parameter. (See “Sample Queue Query” on page 394 for illustra-
tion.)

6 Access an unlocked Work Object that meets the search criteria, now in
QueueQueryHandle.

Call check (VWServer.VW_QQueryNextWorkObject

(QueueQueryHandle,
QueueElementHandle),
“VW_QQueryNextWorkObject”)

If UBound(LogRecords) > LBound(Log Records) Then

For i = 0 To UBound(LogRecords)
Call ParseLogEntry(LogRecords(i))
Next i
End if

7 Lock the Work Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 144

 Work Performance

Call check (VWServer.VW_LockWorkObject

(QueueElementHandle,
OperationHandle),
“VW_LockWorkObject”)

8 Get and set data in the Work Object’s data fields (see “Get Data” on
page 494 and “Set Data” on page 492 to link to API details).

9 Unlock the Work Object and dispatch it to the next queue.

Call check (VWServer.VW_UnlockAndDispatch

(OperationHandle),
“VW_UnlockAndDispatch”)

10 Free resources allocated for the query in step 5:

Call check (VWServer.VW_QQueryEnd

(QueueQueryHandle),
“VW_QQueryEnd”)

Work Performer Comparison

The administrative application runs on the PC workstation only,
whereas the Work Performer runs on the PC workstation or the server.
The designation of active or passive does not apply since it is not a
Work Performer. The administrative application accesses Work Object
data fields directly, rather than through an Operation parameter.

Work Performance
Design your Work Performer to carry out Operations that correspond to
Instructions on the Instruction Sheet of a Work Class. The Work Per-

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 145

 Work Performance

former changes information in the Work Object data fields via the Op-
eration’s parameters. For example, have an Operation of your Work
Performer call an API, input data to the API through the Operation’s pa-
rameters and the API’s input parameters, and change the Work Object
data fields with the API’s output parameters.

Since you are following the guidelines in this chapter, you have chosen
to run the application on the PC workstation. So, you may make the
user’s participation in work sequence active or passive. (See “Push or
Pull (Passive or Active)” on page 34 for definition.)

Passive
Generally, the user launches Performer and Performer starts and stops
a passive Work Performer. Performer resides on the PC workstation,
so, passive Work Performers run, unattended, on the PC workstation.

The developer or user may directly run a passive Work Performer by

designing it to run as an OLE server to an active Work Performer that
is an OLE client (with Windows).

Tip See “Server-side Application” on page 187 for procedures on writing

an active Visual WorkFlo Work Performer that runs unattended on the
server and accomplishes the robot tasks for which you would, other-
wise, write a passive Work Performer.

For information about the passive Work Performer as a design choice,

see “Passive” on page 35.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 146

 Work Performance

Adaptor Use
Visual WorkFlo/Performer and the passive Work Performer communi-
cate through an adaptor. See “Passive Interface with Active Access”
on page 43 for details.

OLE Server Registration

Use of OLE Automation server design requires registration with Mi-
crosoft. FileNET recommends that you design an OLE server to be
self-registering. Some development environments, such as Visual Ba-
sic, register OLE servers when they are built. If the development envi-
ronment you use does not do this, you must write code to register.
Design the OLE server so that when you copy it to a workstation other
than the one on which you built it, it will run to register itself.

Note After re-installation of sample AutoClaim executables, check the regis-

try location of each to see that it is correct. If necessary, run regedit for
each to re-instate the location, as follows:

- Run regedit.

- From the Edit menu, select Find.

- In the Find What box, type the name of the executable (for exam
ple, mfwp.exe.).

- Check the two right most columns for accuracy.

- To correct the path, double click on default.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 147

 Work Performance

- In the value data field of the Edit String box, type the correct path
and click OK.

Passive Work Performer Development: OLE Server

Use this sample procedure to:

Set up with Visual Basic

Set up with Visual WorkFlo/Composer
Align Visual Basic and Visual WorkFlo setups

Follow these steps to explore the development of AutoClaim sample

passive Work Performer code:

Visual Basic Setup

Begin development in the Visual Basic environment, as follows:

1 Run Visual Basic 5.0 from the Start menu.

The New Project window displays. If you were developing a new pas-
sive Work Performer, you would double-click on the ActiveX EXE icon
in the New tab to begin your work.

2 For now, click on the Existing tab, to review development details of an

AutoClaim project.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 148

 Work Performance

3 In the Look in: field of the Existing tab, open the AutoClaim Mainframe
Work Performer project, Mfwp.

This is in the directory where you installed Visual WorkFlo, in the path:

/Samples/Source Code/Mfwp/Mfwp.vbp

An Mfwp project window displays.

4 From the Project menu, select mfwp Properties...

The following screen displays in the foreground:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 149

 Work Performance

5 Note the following:

• The Project Name is MFWP.

• The Project Type is ActiveX EXE.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 150

 Work Performance

The MFWP project developer originally double-clicked on the New

tab icon, ActiveX EXE; so, Visual Basic filled in the Project Type
field for that developer (and for you when you opened this existing
project).

• In the background to the upper right, is the following window:

The window label is Project - mfwp, but to access it from the View
menu, you would select Project Explorer.

• In this Project Explorer window, under Class Modules, is the class

module name Operations, followed by a file name in parenthesis.

If you were developing a new Work Performer, you would add this
class module name yourself, by selecting Add Class Module from

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 151

 Work Performance

the Project menu. (Operations is the class module name the

MFWP project developer assigned. The developer’s assignment of
this name made available to Visual WorkFlo the functions in the
Work Performer Class named Operations; the functions are in the
Visual Basic code, which contains and carries out the Operations
of that Work Performer Class.)

Note that the developer will use this class module name in step 7 of
the Visual WorkFlo setup, below.

• In the background to the center right, is the following window:

The window label is Properties - Operations, but to access it from

the View menu, you would select Properties Window.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 152

 Work Performance

• When you click on the Operations (mfwp.cls) class module in the

Project Explorer window, a second line displays in the Properties
Window Alphabetic tab that shows that the MFWP developer set
Instancing to multiuse.

If you click on 5-Multiuse, you can look at the pull-down options.

Note that multiuse implies that the class is public and creatable.

6 Close the Properties window you opened in step 4.

Visual WorkFlo Setup

Set up the Visual WorkFlo component of the MFWP Work Performer,
as follows:

1 Launch Visual WorkFlo/Composer.

2 From the File menu, select Open and click Yes when the dialog box
asks you “...Continue?”

3 In the Look in: field of the Open Image or CDL File window, open Sam-
ples\AutoClaim.cdl, which is in the directory where you installed Visual
WorkFlo.

The Work Classes view displays.

4 From the View menu, select Work Performer Classes.

Below is part of the screen that displays:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 153

 Work Performance

5 In the Work Performer Classes pane (upper left), scroll down and se-
lect MainframeActivities.

6 In the Operations pane (upper right) select the RetrieveClaimInforma-

tion Operation.

7 Select the Properties tab and note the following:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 154

 Work Performance

• In the Enter an Adaptor name: field, VWOLEADP.DLL is the Adap-

tor Name.

To write a passive Work Performer that is an OLE server, use this

adaptor name, regardless of the environment in which you develop
the Work Performer.

See “Passive Interface with Active Access” on page 43 to compare

this API OLE server interface with that of the passive Work Per-
former that uses the adaptor, VWDLLADP.DLL.

• The Enter an Executable Script name: field contains a combination

(in “dot notation”) of the class module name and the project name.

In our MFWP example, the developer combined the values as-

signed in step 4 of the Visual Basic setup—the Project Name and
the Class Module name—to create the Executable Script name
MFWP.Operations, as shown in the screen below.

Microsoft calls this Executable Script name the progID. The progID
must be in the Windows registry so that Visual WorkFlo/Performer
can launch an instance of the passive Work Performer. Performer’s
launch of this Visual Basic OLE server causes automatic recording
of the progID in the Windows registry. If a progID does not record
to the registry, Performer returns the error, Co-creation.

An NT user sets the path to an OLE server executable file with the
System dialog in the Control Panel.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 155

 Work Performance

8 Minimize Composer and view the Visual Basic window you opened in
step 3.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 156

 Work Performance

Visual Basic and Visual WorkFlo Setup Alignment

Align the setups, as follows:

1 In the Project Explorer window, double-click on the class module

name.

2 The RetrieveClaimInformation Operation code displays, as shown in

the screen below, because you selected that Operation in step 4 of the
Visual WorkFlo setup. This code identifies the entry points to the OLE
server, used by Visual WorkFo to invoke the Operation.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 157

 Work Performance

A B
C D

3 Maximize the Composer window you minimized in step 6, above, and

select its Operation Definition tab.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 158

 Work Performance

The following window displays:

D
B

4 Compare the screens of steps 1 and 2, particularly the values in the

Composer Operation Parameters: columns with the parameter name,
direction mode, and data type in the code.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 159

 Work Performance

5 Note the following:

• The value in the Name: field of the Composer Operation Definition

tab must match the public function name in the code.

In the MFWP project, the value in the Name: field and the public
function name are RetrieveClaimInformation (see the items
marked “A”).

• The spelling of the names listed in the Parameter Name column of

the Composer Operation Definition tab needs not match that of the
method names listed in the code, but the names must appear in the
same order.

For example, in the MFWP project, the Composer Parameter

Name value, foprClaimAmount, has a code counterpart with a dif-
ferent name, ClaimAmount (see the items marked “B”), but each is
the third parameter in its list.

• Parameter direction mode and data type must correspond (see

“Parameter Direction Mode” on page 48 and “Data Type Map Vi-
sual WorkFlo to Visual Basic 5.0” on page 46).

For the MFWP project, the developer used in as the foprClaimAm-

ount parameter mode and the passing style, ByVal (the in mode’s
Visual Basic counterpart) as the ClaimAmount mode (see the
items marked “C”). The Visual WorkFlo data type of the foprClaim-
Amount parameter is float, which corresponds to double in the Vi-
sual Basic passing style (see the items marked “D”).

• Insert your code where the sample says “VB code here.”

• The passive Work Performer may be a subroutine, rather than a

function shown in the code, above.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 160

 Work Performance

If the developer declares a boolean function, as the developer did

in the above code, Visual WorkFlo checks the value that returns
and responds, as follows:

Returned value Visual WorkFlo’s response

True Continues the workflow
False Directs processing of the Work Object to the Malfunc-
tion Instruction Sheet

The sample code declares the boolean in this line:

RetrieveClaimInformation = True

A passive Work Performer that omits such a boolean declaration or

code is a subroutine, rather than a function, and it returns nothing.
For these, Visual WorkFlo assumes that the Operation executed
successfully.

Application Test
Before you run your new application, test it according to the following
procedures.

See “Debugging the Application” on page 177 for reference.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 161

 Work Performance

1 Launch the Work Performer’s development environment (Visual

Basic 5.0 in the example).

2 Load the Work Performer source code (the .vbp file for a Visual Basic
project).

3 Set break points.

4 Run the Work Performer.

5 Launch Visual WorkFlo/Performer.

6 From the Work Performer menu, select Add Work Performer.

7 In the Work Performer Name: field, type the name of the Work Per-
former (MFWP for the example) and click Add.

Performer tries to launch the Work Performer Executable Script, but in-
stead uses the Work Performer you launched in the development envi-
ronment in step 4, above.

8 In the SERVICE SETTINGS column, set Performer to Accepting Work.

Performer locks a Work Object and passes its parameters to the pas-
sive Work Performer Operation. The break points you set allow you to
step through and examine the Work Performer.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 162

 Work Performance

Passive DLL Work Performer Development

Visual WorkFlo can communicates with a passive Work Performer
through the C-language adaptor, VWDLLADP.DLL.

Use the following guidelines to:

• Write a 32-bit passive Work Performer that uses the DLL adaptor.

• Convert between C data type and Visual WorkFlo data type.

1 Before developing the DLL, the user or developer calls it with the pro-
gram, Visual WorkFlo/Composer, as follows:

• Enter the DLL adaptor name in the Properties editor of the Work
Performer Class browser as VWDLLADP.DLL.

• Check that the script name (entered in the same editor) is the
name of the DLL that contains the Operations the Work Performer
will execute.

• Check that each Operation name exactly matches the name of the
entry point of the DLL the Work Performer will call.

2 Observe cdecl and standard Windows far pascal calling conventions:

• Call functions so that they return no value (they have “void” re-
sults).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 163

 Work Performance

• Export all callable functions and check that they have proper Win-
dows pre- and post-ambles.

• Pass all parameters in the order declared during authoring.

Your application uses no parameter name in the actual call, so the

name can be anything you wish.

Conversion of Data Type

Visual WorkFlo passes parameters to the passive Work Performer via
the adaptor, VWDLLADP.DLL. The Work Performer changes them,
then sends them back to the adaptor.

Adaptor to passive Work Performer. When Visual WorkFlo passes a

parameter to your passive Work Performer via the DLL adaptor, the pa-
rameters convert to C data types, as shown in the following table:

Visual WorkFlo C
integer long
float double
boolean BOOL (int or long)
string char far *, points to null terminated string
time FN_time_typ (long)

An array of Visual WorkFlo data types passes as contiguous, sequen-

tial memory locations of the corresponding ‘C’ data (packed to 4-byte
alignment or not packed, depending on what is standard for the plat-
form). Note that the data of a string is in a separate memory area,
rather than directly in the array; the array passes as a far pointer to the
data followed by an unsigned integer that is the number of elements in
the array.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 164

 Work Performance

Passive Work Performer to adaptor. When parameters return from

an application to the DLL adaptor, they pass in as the following data
types:

C Visual WorkFlo
long far * integer
double far * float
BOOL far * (int or long far *) boolean
char **HGLOBAL far * string
FN_time_typ far * (long far *) time

Arrays of the above data items return as contiguous, sequential mem-

ory locations of the above input parameters (packed to 4-byte align-
ment). Note that the data for strings is in separate memory areas,
rather than directly in the array.

Procedures
Procedures for developing with this conversion follow:

1 Write the passive Work Performer so that it stores the result values via
the passed-in pointers.

2 Allocate string data and return a pointer to the memory where the
string data is stored.

Use the default process heap (obtain this by a call to GetProcessHeap)

to allocate the string data.

3 Null terminate the string.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 165

 Work Performance

4 Pass an “HGLOBAL far *” followed by an “unsigned far *” a “void *” fol-

lowed by an “unsigned * (long *)” on the stack when you expect an ar-
ray as the result. The routine your passive Work Performer calls must
allocate the data, put the handle in the HGLOBAL (the pointer in the
void*), and put the number of array elements in the unsigned.

Inout Parameters. Inout parameters pass as result parameters, ex-

cept that the values are all filled in. It is legitimate for a string or an ar-
ray to be one length as it passes in and another length upon return.

Memory Allocation. Visual WorkFlo deallocates the memory to which

all pointers and handles point, after the call returns. Check that the rou-
tine your passive Work Performer calls does not deallocate an item
that the adaptor passed in (unless it is an inout HGLOBALs pointer for
which the handlepointer itself has been changed). Also, check that the
routine makes a copy of a parameter it wishes to preserve beyond the
length of the call.

If a passive Work Performer declares an input parameter of type inte-

ger with the name F_OperationHandle, the OperationHandle replaces
the value specified in the Instruction; therefore, make the parameter in
the Instruction zero. OperationHandle can be in any position in the pa-
rameter list, giving you access to the Operation parameters.

Active
The user or developer, rather than Performer, starts and stops an ac-
tive Work Performer. For information about the active Work Performer
as a design choice, see “Active” on page 36.

An active Work Performer can be an OLE client and use the services
of an OLE server. See “Creative, Administrative, and Active Work Per-

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 166

 Work Performance

former Interface with the API OLE Server” on page 40 and “Passive In-
terface with Active Access” on page 43 for details.

Active Work Performer Development: OLE Client

Review this sample active Work Performer, noting that user participa-
tion is more interactive than it was with the passive Work Performer we
developed in the previous section. Follow this section’s guidelines to:

Set up with Visual Basic

Set up with Visual WorkFlo/Composer
Align Visual Basic and Visual WorkFlo setups
Set and get data

Visual Basic Setup

Follow these procedures to trace the development of a sample active
Work Performer that is an OLE client:

1 Run Visual Basic 5.0 from the Start menu.

The New Project window displays. If you were developing a new active
Work Performer, you would double-click on the Standard EXE icon in
the New tab to begin your work.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 167

 Work Performance

2 Since we are using an example that installed with Visual WorkFlo, click
on the Existing tab (to review development details of a project in the
AutoClaim sample).

3 In the Look in: field of the Existing tab, open the AutoClaim Estimator
Assigns Work Performer project, EstAssigns.

This is in the directory where you installed Visual WorkFlo, in the path:

/Samples/Source Code/EstAssigns/EstAssigns.vbp

An EstAssigns project window displays.

4 From the Project menu, select EstAssigns Properties...

The following screen displays in the foreground.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 168

 Work Performance

The developer selected the Standard EXE icon in the New tab to de-
velop this sample; so, that is the value that appears in the Project Type:
field, above. The developer’s selection of Standard EXE set up the ac-
tive Work Performer so that can be an OLE client when it compiles.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 169

 Work Performance

In the background to the upper right, is the following window:

The window label is Project - EstAssigns (to access it from the View
menu, you would select Project Explorer).

5 Close the Properties window you opened in step 4.

Visual WorkFlo Setup

1 Launch Visual WorkFlo/Composer.

2 From the File menu, select Open and click Yes when the dialog box
asks you “...Continue?”

3 In the Look in: field of the Open Image or CDL File window, open Sam-
ples\AutoClaim.cdl, which is in the directory where you installed Visual
WorkFlo.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 170

 Work Performance

The Work Classes view displays.

4 From the View menu, select Work Performer Classes.

5 From the Work Performer Classes pane in the upper left, select Esti-
mator Assignments.

6 From the Operations pane in the upper right, select the EstimatorPick
Operation. The following screen displays.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 171

 Work Performance

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 172

 Work Performance

Alignment of Visual Basic and Visual WorkFlo Setups

1 Minimize Composer and view the Visual Basic window you opened.

2 In the Project Explorer window, double-click on the module name

(modEstPick in the example).

3 In the upper right field, scroll and select (Declarations).

The modEstPick Operation code displays, as follows, because you se-

lected that Operation in step 6 of the Visual WorkFlo setup.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 173

 Work Performance

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 174

 Work Performance

4 The following code illustrates how the Visual Basic active Work Per-
former accesses the Operation parameters defined in Composer:

5 Compare the screens of steps 3 and 4, above, with that of the Com-
poser Operation Definition tab in Visual WorkFlo Setup step 6.

In particular, compare the values in the Composer Operation Parame-

ters: columns with the parameter name, direction mode, and data type
in the code samples.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 175

 Work Performance

6 Note the following:

• Although parameter order was important when we developed the

passive Work Performer, it is irrelevant in this active Work Per-
former code (because the user will access the parameters as
needed).

• The parameter name, soprClaimNumber, must be consistent be-

tween the Visual WorkFlo API call VW_SetString and the
Parameter Name column of the Composer Operation Definition
tab.

• If we call an API to set data, the data direction mode must be out or
inout.

• If we call an API to get data, the data direction mode must be in or

inout.

• If we call an API to get and set data, the data direction mode must
be inout.

Application Test
Before you run your new Work Performer, test it according to the fol-
lowing procedures. Also, see “Debugging the Application” on page 177
for reference.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 176

 Debugging the Application

1 Check whether there are any Work Objects in the queue that the Work
Performer can read (a filter may prevent the reading of some, for exam-
ple).

2 Start up the Work Performer’s development environment.

3 Set break points.

4 Run the Work Performer, stepping through part of it at a time.

Debugging the Application

Use the following Visual WorkFlo features to assist in debugging the
application:

• Code that indicates Operation failure or success

• Calls to logging and statistic APIs

• A log of interaction between the application and the API

• A Work Performer that dumps Work Object contents to a log

• A user-interface button for API pairs

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 177

 Debugging the Application

Indicating Operation Success or Failure

If you wish to allow the passive Work Performer to cancel an Opera-
tion, design it to return a boolean value to indicate success or failure of
the Operation, as follows:

Value
Returned Status
TRUE Visual WorkFlo copies the inout and out parameter values
into the Work Object and dispatches the Work Object to
the next Instruction.
FALSE Visual WorkFlo does not copy the inout and out parameter
values into the Work Object and it calls the Malfunction In-
struction Sheet to process the Work Object.

Enter a statement, such as the following in your Work Performer code:

RetrieveClaimInformation = True

See the following example of this in the next-to-last line of code above
Step 3 on page 158.

Calling Log and Statistic APIs

Design your Work Performer to call these APIs:

“VW_LogMessage” on page 370

“VW_LogQueryBegin” on page 381

“VW_LogQueryEnd” on page 383

“VW_LogQueryNextRecords” on page 384

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 178

 Debugging the Application

“VW_QueueGetStats” on page 415

“VW_RosterGetStats” on page 423

Logging API Module Interaction (SVCAPI Trace Logging)

Logging your application’s interaction with the SVCAPI module allows
you to see the following:

Exceptions thrown
Errors returned
Calls to APIs

To enable SVCAPI trace logging, set the LogToFile entry in the client
workstation’s VW.INI file or in the server’s vwclient.ini file to 1.

Contrast this type of logging with event logging, described in the details
of “VW_LogMessage” on page 370.

Dumping Work Object Contents: NDump Work Performer

See the sample Work Performer NDump in the Samples directory
where you installed Visual WorkFlo. You can use a Work Performer
such as this to dump the contents of Work Objects to a log.

This sample assumes the Work Performer Class, NDumpWP. In the

queue of this Work Performer Class, the NDump Work Performer que-
ries for Work Objects and dumps their contents to a file. (The sample
log file default name is ndump.log.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 179

 Debugging the Application

Running NDump
When you run ndump.exe from the Samples directory, it displays the
following window:

The window caption displays the name of the Work Performer and the
path and name of the output file.

The File menu has two options, Log file or Exit, as shown in the follow-
ing screen:

Select Log file to specify the filename and location of the dump output.

Select Exit to exit the NDump Work Performer.

Sample NDump Log

Sample output of the NDump Work Performer follows:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 180

 Performance Optimization

Date and time Work Object name

of dump
4/15/98 4:57:30 PM *
i integer 99
b boolean false
f float 99.99
s string ‘99’
t time ‘16:56:34 4/15/1998’
ia integer array {88,77}
ba boolean array {false,true}
fa float array {99.99,88.88}
sa string array {‘99’,’88’}
ta time array {‘16:56:34 4/15/1998’,’16:56:34 4/15/1998’}

Either no lines or one line per Work Object data field prints after the
first line, above. This sample shows a line of output for each Visual
WorkFlo data type.

Using the UI Button for API Pairs

An error occurs when a Visual WorkFlo application fails to call the sec-
ond in a pair of API functions. (Paired API functions are those that have
a second API function that must be called to release resources allo-
cated by the first API function. See “API Pairs” on page 253.) For pur-
poses of debugging, consider modifying your Work Performer to
provide a button on the user interface (UI) that, when clicked, calls both
functions of an API pair.

Performance Optimization
Optimize performance by incorporating the following practices into de-
velopment of your Visual WorkFlo application:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 181

 Performance Optimization

• Design for re-use.

• Track Operation parameters.

• Limit the number of entries in a Work Queue (keep queue depth

shallow).

• Run the utility, wal_purge, during development (compare this to

running it as part of maintenance).

• Consider the tradeoffs in Work Performer Operation granularity.

• Valdate data fields

• Use sequenced mode

• Access WAL-related error messages

Reuse
An advantage of the Work Performer application is that you may design
it for reuse. Rather than run it once with exact Work Object data field
names (as you would an administrative application), you can design it
with Operations that have parameters, to which Visual WorkFlo can
map Work Object data fields repeatedly.

When possible, design a Work Performer Operation so that it is reus-

able, without sacrificing its effectiveness by making it too general. If its
Operations are reusable, a Work Performer is small and easy to main-
tain and you can quickly use it to automate a new business process.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 182

 Performance Optimization

Operation and Parameter Tracking

A Work Performer’s Operation uses the following for each of its param-
eters:

Data type appropriate to the development environment

Corresponding Visual WorkFlo data type
Direction mode

FileNET recommends that you keep a list, such as the following, handy
during development to track this information for each parameter:
WP_autoclaim: SampleWP_1

OLE Direct Visual

Parameter Wrapper OLE Server WorkFlo
Operation Name DLL Interface Type Mode
1 Parameter_1 long Not applicable integer in
for this Work
Performer
Parameter_2 double float out
Parameter_3 char * string in
Parameter_4 BOOL boolean inout
2 Parameter_1 long integer in
Parameter_2 BOOL boolean inout
Parameter_3 char * string in
Parameter_4 double float out

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 183

 Performance Optimization

Number of Work Queues

and Work Queue Fields
An administrative or active Work Performer application browses Work
Queue fields to find those of interest the user. The number of these
fields and the number of Work Queues can affect performance.

FileNET recommends design that accesses many queues that have

few entries (fields) rather than a few queues with many entries.
Searching for a Work Object or sorting the Work Objects is more effi-
cient when queues are shallow, because there are fewer entries to
search and sort. (See Visual WorkFlo Technical Notes for details.)

wal_purge During Development

It is essential to run the utility, wal_purge, as part of application devel-
opment, rather than wait to run it as a maintenance procedure. This
keeps memory space clean and free of semaphores. It minimizes seg-
mentation during startup and takes full advantage of the utility’s bene-
fits (when compared to running it during maintenance). Rather than
run this utility during production, FileNET recommends a call to techni-
cal support staff to explore designing it into the application.

The wal_purge utility is in /fnsw/client/bin.

Locking Work Objects

Between the time your application begins browsing and the time it
locks a Work Object another application can lock the Work Object. Be-
gin your browse again if this happens.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 184

 Performance Optimization

Operation Granularity
Granularity is the amount of work accomplished by a Work Performer
Operation. A small-grained Operation is one that does little, such as
displaying a print dialog box for user input. A large-grained Operation
performs logically related business steps, such as providing forms into
which a loan officer enters customer and loan data, then calculating a
payment schedule based on that data.

Because Visual WorkFlo must queue work between execution of each

Work Performer Operation, small-grained Operations can diminish per-
formance. However, the larger the granularity, the more specific and
less reusable the Operation becomes. To balance these consider-
ations, design an Operation to accomplish one business task, such as
writing a check or verifying application information.

Validation Checking
Design a Visual WorkFlo application to validate data fields, Operation
parameters, and Work Queue fields before it uses them. Have it verify
that numeric values are within the acceptable range and that a string is
null only when expected.

Include code that handles exceptions during processing of a Work Ob-

ject. An application may need to call the Malfunction Instruction Sheet
to handle invalid data problems and you may need to create new In-
struction Sheets to handle specific data errors.

Sequenced Mode
See “VW_SequencedWait” on page 428 for a discussion of sequenced
mode. Note that although a passive Work Performer does not call the

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 185

 Performance Optimization

API, it uses sequenced mode as conceptually described by this API

detail. A passive Work Performer processes Work Objects that are ei-
ther in sequenced mode or not in sequenced mode; it cannot process
a mix. If PassiveSequenced=1, the passive Work Performer process
Work Objects that are in sequenced mode, only. If PassiveSe-
quenced=0, the passive Work Performer processes only those Work
Objects that are not in sequenced mode.

Sequenced mode is available for Desktop-environment Work Perform-

ers only.

WAL Error Messages

If you will compile and use WAL, select the WAL_ERR_ENCODE op-
tion when you compile. This uses the ErrEncode.h file included with
your WAL installation.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 186

 3
3Server-side Application

Begin the procedures in this chapter when you have:

• Decided to run a Visual WorkFlo application with client software on

the Visual WorkFlo server (AIX or HP-UX platform)

To develop a server-side application that runs on the Windows NT,

follow the same procedures as for an application that runs on the
PC workstation (see “Client-side Application” on page 55).

• Completed the “Predevelopment Checklist” on page 25

• Decided that the developer’s participation in Work Object

sequencing will be active

Go to Select one of the following, if you wish to begin directly with procedures
Procedures for developing a Visual WorkFlo application that runs on the server:

“Work Performer on the AIX” on page 190

“Work Performer on HPUX” on page 229

Otherwise, continue with this chapter’s guidelines to:

• Review the details of Visual WorkFlo client software on the Visual

WorkFlo server

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 187

 Server-side Application
Client Software on the Server

• Run an application that is an active Work Performer on the Visual

WorkFlo server

You are developing an application that will either use the C-language
DLL , SVCAPI.DLL, or interface directly with the API OLE server,
VWAPISRV.EXE. This Work Performer application is active, in that you
predetermine in its code the sequence in which Visual WorkFlo will
process Work Objects, before you run it on the Visual WorkFlo server.
(Compare this to an active Work Performer you run on the PC worksta-
tion, where you determine the sequence, but can interrupt the Work
Performer to change the sequence.)

Client Software on the Server

Each server on which Visual WorkFlo is installed has the logical divi-
sion of client and server areas. A Visual WorkFlo application runs, with
client software, in the client area of the server or on a PC workstation.
(See Getting Started with Visual WorkFlo for information about client
software in a system overview.)

The developer designs an application to run on the server, rather than

the PC workstation, for various reasons. For example, this minimizes
PC workstation-server transaction when there is little requirement for
user interface.

See “Predevelopment Checklist” on page 25 for information about us-

ing Visual WorkFlo programs in conjunction with the client software
and your application source code. The following reside in the client
area of the server:

• Developer’s application source code

• Header file (.H suffix)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 188

 Server-side Application
Compilation

• Shared library or DLL (API code) in C language

• WorkFlo Application Libraries (WAL)

On the server, WAL uses the client area of memory, which is sepa-
rate from the memory used by the server software. A firewall pro-
tects server software in the event of a server-side application
anomaly. A server-side application (which resides in the client
area, on the same side of the firewall as WAL) uses BIN, IN-
CLUDES, and SHOBJ directories that are parallel to those used by
the server software on the opposite side of the firewall. (A client-
side application, that is an application that resides on the PC work-
station, uses the WAL on the PC client.)

See the Visual Work Flo Installation and Administration Handbook and
the Visual WorkFlo Glossary for information about the following Visual
WorkFlo initialization files:

VW.INI Client-side, user-defined applications and FileNET-

provided programs on the PC workstation
vwclient.ini Server-side Work Performers (AIX or HP-UX plat-
forms)
vwserver.ini Date/time mask specification for system software on
the server

Compilation
Compile a server-side active Work Performer with the following:

Includes in /fnsw/client/include
Libraries in /fnsw/client/shobj

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 189

 Server-side Application
Compilation

Work Performer on the AIX

Develop a server-side active Work Performer to run on your AIX plat-
form, using the sample applications on the Visual WorkFlo 3.01 CD as
guides.

There are two samples to run on the AIX:

VWSample
Unattended

Procedures follow for using these.

Sample AIX Work Performer: VWSample

1 Find the following files:

vwsample.c
vwmksample
vwsample.cdl

These are on the client PC, where you installed Visual WorkFlo, in this
directory:

Samples\AIX_Sample\

2 Transfer the step 1 files from the CD, as follows:

• Move these into a directory on the server:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 190

 Server-side Application
Compilation

vwsample.c
vwmksample

Use ftp, for example, to transfer them.

• Transfer vwsample.cdl with Visual WorkFlo\Conductor.

See the Predevelopment Checklist, mentioned at the beginning of

this chapter, for context.

3 Enter this line of code at the prompt to begin development of your

server-side Work Performer:

chmod +x filename

For filename, substitute the name of your script file. (In the case of this
sample, it is vwmksample.)

This causes the application to execute the modifications you make in

the script file attributes.

4 Write a script file with code similar to that in vwmksample, as shown

below:

cc -qchars=signed -g -DVW_SERVER -I/fnsw/client/include -c vwsample.c

xlC_r -qchars=signed -g -DVW_SERVER -I/fnsw/client/include -bnoquiet \
/fnsw/client/shobj/vwapiexp.o \
-o vwsample vwsample.o

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 191

 Server-side Application
Compilation

The application uses this script as the basis for compilation. Your com-
piler may require a script that is slightly different from the sample, but
the script must:

• Indicate the location of the include files (which contain svcapi.h)

• Contain linking information

The first line of sample code, above, creates the object file. The sec-
ond line links the object file to other object files in the application and
creates an executable (vwsample*, in this case).

5 Follow these procedures for each of your C files:

• Replace wpsample.c, in the step 5 script with the name of your

script file.

• In the last line, replace wpsample wpsamsple.o with the name

of your executable, followed by each object file you create.

(There is one object file for each C file.)

6 At the prompt, enter the command: vwmksample.

This causes the application to use the code in vwsample.c to create an

executable, vwsample*. The code in vwsample.c follows. It is a series
of procedures, at the end of which is the main routine that logs onto Vi-
sual WorkFlo, uses the procedures, then logs off of Visual WorkFlo.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 192

 Server-side Application
Compilation

This sets up include files and indication of whether the code runs suc-
cessfully:

#include <stdio.h>
#include <string.h>

#include <svcapi.h>

#define success 0

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 193

 Server-side Application
Compilation

The following enables various executable tasks, as described in the

code’s comments:

void print_usage(void)
{
printf ("\
Usage: vwsample {-c <wcname> | -q <wpcname> [-a] }\n\
-m <wpcname> | -g <wpcname>\n\
where '-c <wcname>' creates a work object of work class '<wcname>'.\n\
\n\
'-q <wpcname>' reads a work object from the queue of work\n\
performer class '<wpcname>' and dispatches it to the next\n\
queue according to the instruction sheet.\n\
'-a' indicates repeat for all work objects in queue.\n\
\n\
'-m <wpcname>' indicates to perform some miscellaneous API calls.\n\
\n\
'-g <wpcname>' perform get and sets on a work object from the queue\n\
of work performer class '<wpcname>'\n\
");
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 194

 Server-side Application
Compilation

The following causes Visual WorkFlo to return a zero (and display a

success message) if the application runs sucessfully; otherwise, it
causes an error message to return:

int print_return(char* procName, VW_Error error)

{
VW_MessageType message;

if (error)
{
printf("Got an error during %s.\n", procName);
VW_GetErrorMessage(error, message);
printf("The error is: %s \n", message);
return -1;
}
else
printf("%s was successful.\n", procName);

return 0;
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 195

 Server-side Application
Compilation

The following procedure creates a Work Object, then dispatches it:

int createWob(VW_LogonHandle logonId, char* wcnamep)

{
VW_NewWorkObjectHandle newWobId;
VW_Error error = success;

error = VW_CreateWorkObject(logonId, wcnamep, &newWobId);

if ( print_return("VW_CreateWorkObject", error) < 0)
return -1;

error = VW_DispatchWorkObject(newWobId);
if ( print_return("VW_DispatchWorkObject", error) < 0)
return -1;

return 0;
}

See “Locator” on page 242 for a link to details regarding API calls,
such as those in the above code to VW_CreateWorkObject( ) and VW_
DispatchWorkObject( ).

The following attaches to a queue, browses the queue to find a Work

Object, returns the name of the current Operation, then dispatches the
Work Object:

int dqWob(VW_LogonHandle logonId, char* qnamep, VW_Boolean doAll)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 196

 Server-side Application
Compilation

{
VW_QueueHandle workQueueId;
VW_ActiveWPHandle workPerformerId;
VW_BrowseHandle browseId;
VW_BrModHandle browseModHandle=0;
VW_QueueElementHandle queueElementId
VW_OperationHandle operationId;
VW_OperationNameType operationName;
unsigned long workObjectCount;
VW_Error error=success;

error = VW_AttachToWorkQueue(logonId, qnamep, &workQueueId);

if ( print_return("VW_AttachToWorkQueue", error) < 0)
return -1;

error = VW_ReportToWork(workQueueId, &workPerformerId);

if ( print_return("VW_ReportToWork", error) < 0)
return -1;

error = VW_BeginBrowsingWorkQueue(workPerformerId, &browseId, 20, &workObject-

Count, browseModHandle);
if ( print_return("VW_BeginBrowsingWorkQueue", error) < 0)
return -1;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 197

 Server-side Application
Compilation

if (workObjectCount < 1)
{
if (doAll)
return -1;
}
while (workObjectCount) {
workObjectCount--;
error = VW_NextWorkObjectToBrowse(browseId, &queueElementId);
if ( print_return("VW_NextWorkObjectToBrowse", error) < 0)
return -1;

error = VW_LockWorkObject(queueElementId, &operationId);

if ( print_return("VW_LockWorkObject", error) < 0)
return -1;

error = VW_GetOperationName(operationId, operationName);

if ( print_return("VW_GetOperationName for operationId", error) < 0)
return -1;
else
{
printf("The operation name is: %s", operationName);
printf("\n");
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 198

 Server-side Application
Compilation

error = VW_UnlockAndDispatch(operationId);
if ( print_return("VW_UnlockAndDispatch", error) < 0)
return -1;

if (!doAll)
break;
}
error = VW_EndBrowsingWorkQueue(browseId);
if ( print_return("VW_EndBrowsingWorkQueue", error) < 0)
return -1;

error = VW_LeaveWork(workPerformerId);
if ( print_return("VW_LeaveWork", error) < 0)
return -1;

error = VW_DetachFromWorkQueue(workQueueId);
if ( print_return("VW_DetachFromWorkQueue", error) < 0) return -1;

return 0;
}

The following attaches to a queue, browses the queue to find a Work

Object, gets and sets fields in the Work Object, then dispatches the
Work Object:

int GetAndSet (VW_LogonHandle logonId, char* qnamep, VW_Boolean doAll)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 199

 Server-side Application
Compilation

{
VW_QueueHandle workQueueId;
VW_ActiveWPHandle workPerformerId;
VW_BrowseHandle browseId;
VW_BrModHandle browseModHandle=0;
VW_QueueElementHandle queueElementId
VW_OperationHandle operationId;
VW_OperationNameType operationName;
VW_Handle workerHandle
VW_WobAccessHandle wobAccessHandle
VW_Integer theInteger
VW_Boolean theBoolean
VW_String theString
unsigned long workObjectCount;
unsigned int theSize
VW_Error error=success;

error = VW_AttachToWorkQueue(logonId, qnamep, &workQueueId);

if ( print_return("VW_AttachToWorkQueue", error) < 0)
return -1;

error = VW_ReportToWork(workQueueId, &workPerformerId);

if ( print_return("VW_ReportToWork", error) < 0)
return -1;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 200

 Server-side Application
Compilation

error = VW_BeginBrowsingWorkQueue(workPerformerId, &browseId, 20, &workObject-

Count, browseModHandle);
if ( print_return("VW_BeginBrowsingWorkQueue", error) < 0)
return -1;

if (workObjectCount < 1)
{
if (doAll)
return -1;
}
while (workObjectCount) {
workObjectCount--;
error = VW_NextWorkObjectToBrowse(browseId, &queueElementId);
if ( print_return("VW_NextWorkObjectToBrowse", error) < 0)
return -1;

error = VW_GetOperationName(queueElementId, operationName);

if ( print_return("VW_GetOperationName for queueElementId", error) < 0)
return -1;
else
{
printf("The operation name is: %s", operationName);
printf("\n");
}

error = VW_GetAccessHandle(queueElementId, 1, &wobAccessHandle);

if ( print_return("VW_GetAccessHandle", error) < 0)
return -1;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 201

 Server-side Application
Compilation

error = VW_GetInteger(wobAccessHandle, "xinteger", &theInteger);

if ( print_return("VW_GetInteger", error) < 0)
return -1;
else
{
printf("The integer is %ld.", theInteger);
printf("\n");
}

error = VW_GetBoolean(wobAccessHandle, "xboolean", &theBoolean);

if ( print_return("VW_GetBoolean", error) < 0)
return -1;
else
{
printf("The boolean is %ld.", theBoolean);
printf("\n");
}

error = VW_GetStringSize(wobAccessHandle, "xstring", &theSize);

if ( print_return("VW_GetStringSize", error) < 0)
{
return -1;
}
else
{
printf("The string size is %ld.", theSize);
printf("\n");
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 202

 Server-side Application
Compilation

theString = (char*)malloc(theSize+1);
error = VW_GetString(wobAccessHandle, "xstring", theString);
if ( print_return("VW_GetString", error) < 0)
{
return -1;
}
else
{
printf("The string is %s.", theString);
printf("\n");
}
free(theString);

error = VW_SetInteger(wobAccessHandle, "xinteger", theInteger + 1);

if ( print_return("VW_SetInteger", error) < 0)
return -1;

error = VW_SetString(wobAccessHandle, "xstring", "abc");

if ( print_return("VW_SetString", error) < 0)
return -1;

error = VW_SetBoolean(wobAccessHandle, "xboolean", theBoolean ? 0 : 1);

if ( print_return("VW_SetBoolean", error) < 0)
return -1;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 203

 Server-side Application
Compilation

error = VW_FreeAccessHandle(wobAccessHandle, 1, 0, "");

if ( print_return("VW_FreeAccessHandle", error) < 0)
return -1;

if (!doAll)
break;
}
error = VW_EndBrowsingWorkQueue(browseId);
if ( print_return("VW_EndBrowsingWorkQueue", error) < 0)
return -1;

error = VW_LeaveWork(workPerformerId);
if ( print_return("VW_LeaveWork", error) < 0)
return -1;

error = VW_DetachFromWorkQueue(workQueueId);
if ( print_return("VW_DetachFromWorkQueue", error) < 0)
return -1;

return 0;
}

The following acquires miscellaneous administrative information: the

machine ID, the isolated region number, and the queue depth:

int Misc (VW_LogonHandle logonId, char* workClassName)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 204

 Server-side Application
Compilation

{
VW_MachineIdNameType machineId;
VW_IsolatedRegionType isolatedRegion;
long workQueueDepth;
VW_Error error=success;

error = VW_GetMachineId(logonId, machineId);

if ( print_return("VW_GetMachineId", error) < 0)
return -1;
else
{
printf("The machine id is: %s", machineId);
printf("\n");
}

error = VW_GetIsolatedRegion(logonId, &isolatedRegion);

if ( print_return("VW_GetIsolatedRegion", error) < 0)
return -1;
else
{
printf("The isolated region is: %ld", isolatedRegion);
printf("\n");
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 205

 Server-side Application
Compilation

error = VW_GetWorkQueueDepth(logonId, workClassName, &workQueueDepth);

if ( print_return("VW_GetWorkQueueDepth", error) < 0)
return -1;
else
{
printf("The work queue depth is: %ld", workQueueDepth);
printf("\n");
}

return 0;

The final segment of the vwsample.c code is the main routine, which
logs on and off of Visual WorkFlo and uses the above procedures:

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

{
long objectCount = 1;
char* className = NULL;
long i, j;
VW_Boolean doAll = FALSE;
VW_Error error = success;
VW_LogonHandle logonID;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 206

 Server-side Application
Compilation

if (argv[1][0] != ‘-’)
{
print_usage()
return -1;
}
for (i = 1; i < argc; i++)
{
if (argv[i][0] != '-')
{
print_usage();
return -1;
}
switch (argv[i][1])
{
case 'q':
case 'c':
case 'm':
case 'g':
if (i + i >= argc)
{
print_usage();
return -1;
}
className = argv[i+1];
i++;
break;
case 'a':
doAll = TRUE;
break;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 207

 Server-side Application
Compilation

default:
print_usage();
break;
}
}
if ( className == NULL )
{
print_usage();
return -1;
}

error = VW_LogonEx("User", "Password", "VWService1:homer:FileNet", 1, &logonID);

if ( print_return("VW_LogonEx", error) < 0)
return -1;

for (i = 0, j = -1; i < objectCount; i++)

{
if (argv[1][1] == 'c')
{
if (createWob(logonID, className) < 0)
return -1;
}
else if (argv[1][1] == 'q')
{
if (className == NULL)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 208

 Server-side Application
Compilation

{
print_usage();
return -1;
}
if ( dqWob(logonID, className, doAll) < 0)
{
VW_Logoff(logonID);
return -1;
}
}
else if (argv[1][1] == 'm')
{
if (className == NULL)
{
print_usage();
return -1;
}
if (Misc(logonID, className) < 0)
return -1;
}
else if (argv[1][1] == 'g')
{
if (className == NULL)
{
print_usage();
return -1;
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 209

 Server-side Application
Compilation

if ( GetAndSet(logonID, className, doAll) < 0)

{
VW_Logoff(logonID);
return -1;
}
}
else
{
print_usage();
return -1;
}
}
error = VW_Logoff(logonID);
if ( print_return("VW_Logoff", error) < 0)
return -1;

printf ("Program completed successfully\n");

return 0;
}

7 At the prompt, type the executable command: vwsample.

8 Append a task and a Work Class name or Work Performer Class

name, such as one of those shown on page 194. (Note the number of
this page so that you can easily return to it.)

Sample display results follow:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 210

 Server-side Application
Compilation

>vwsample -c SimpleWP
VW_LogonEx was successful.
VW_CreateWorkObject was successful.
VW_DispatchWorkObject was successful.
VW_Logoff was successful.
Program completed successfully.

>vwsample -q WPSample
VW_LogonEx was successful.
VW_AttachToWorkQueue was successful.
VW_ReportToWork was successful.
VW_BeginBrowsingWorkQueue was successful.
VW_NextWorkObjectToBrowse was successful.
VW_LockWorkObject was successful.
VW_GetOperationName was successful.
The operation name is: InputString
VW_UnlockAndDispatch was successful.
VW_EndBrowsingWorkQueue was successful.
VW_LeaveWork was successful.
VW_DetachFromWorkQueue was successful.
VW_Logoff was successful.
Program completed successfully.

>vwsample -m WPSample
VW_LogonEx was successful.
VW_GetMachineId was successful.
The machine id is: 6
VW_GetIsolatedRegion was successful.
The isolated region is: 89
VW_GetWorkQueueDepth was successful.
The work queue depth is: 1

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 211

 Server-side Application
Compilation

VW_Logoff was successful.

Program completed successfully.

>vwsample -g WPSample
VW_LogonEx was successful.
VW_AttachToWorkQueue was successful.
VW_ReportToWork was successful.
VW_BeginBrowsingWorkQueue was successful.
VW_NextWorkObjectToBrowse was successful.
VW_LockWorkObject was successful.
VW_GetOperationName was successful.
The operation name is: InputString
VW_GetAccessHandle was successful.
VW_GetIntegerwas successful.
The integer is 23.
VW_GetBoolean was successful.
The boolean is 1.
VW_GetStringSize was successful.
The string size is 6.
VW_GetString was successful.
The string is apples.
VW_SetInteger was successful.
VW_SetString was successful.
VW_SetBoolean was successful.
VW_FreeAccessHandle was successful.
VW_EndBrowsingWorkQueue was successful.
VW_LeaveWork was successful.
VW_DetachFromWorkQueue was successful.
VW_Logoff was successful.
Program completed successfully.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 212

 Server-side Application
Compilation

Sample AIX Work Performer: Unattended

1 Find the following files:

unattended.c
AIX_Build
unattended

These are on the client PC, where you installed Visual WorkFlo, in this
directory:

Samples\AIX_Unattended

2 Transfer the step 1 files from the CD into a directory on the server, us-
ing ftp, for example.

3 Transfer AutoClaim.cdl to your server with Visual WorkFlo\Conductor.

This is on the client PC, where you installed Visual WorkFlo, in this di-
rectory:

Samples\AutoClaim\

See the Predevelopment Checklist, mentioned at the beginning of this

chapter, for context.

4 Enter this line of code at the prompt to begin development of your

server-side Work Performer:

chmod +x filename

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 213

 Server-side Application
Compilation

For filename, substitute the (case-sensitive) name of your script file. (In
the case of this sample, it is AIX_Build.)

This causes the application to execute the modifications you make in

the script file attributes.

5 Write a script file with code similar to that in AIX_Build, as shown be-
low:

cc -qchars=signed -g -DVW_SERVER -I/fnsw/client/include -c unattended.c

xlC_r -qchars=signed -g -DVW_SERVER -I/fnsw/client/include -bnoquiet \
/fnsw/client/shobj/vwapiexp.o \
-o unattended unattended.o

The application uses this script as the basis for compilation. Your com-
piler may require a script that is slightly different from the sample, but
the script must:

• Indicate the location of the include files (which contain svcapi.h)

• Contain linking information

The first line of sample code, above, creates the object file. The sec-
ond line links the object file to other object files in the application and
creates an executable (unattended*, in this case).

6 Follow these procedures for each of your C files:

• Replace unattended.c, in the step 5 script with the name of your

script file.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 214

 Server-side Application
Compilation

• In the last line, replace unattended unattended.o with the

name of your executable, followed by each object file you create.

(There is one object file for each C file.)

7 At the prompt, enter the command: AIX_Build.

This causes the application to use the code in unattended.c to create

an executable. The code in unattended.c follows. It is a series of proce-
dures that creates vouchers and correspondence at the end of the Au-
toClaim process, after the adjustor has reviewed the claim.

#include <stdio.h>
#include <string.h>
#include <signal.h>

#ifdef _WIN32
#include <stdlib.h>
#define sleep _sleep
#define SECONDS 1000
#else
#define SECONDS 1
#include <unistd.h>
#endif

#include <svcapi.h>
#include <vwerrors.h>

#define NIL NULL

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 215

 Server-side Application
Compilation

/* Default Constants */
#define IDLE_POLLING_INTERVAL "10"
#define USERID "SysAdmin"
#define PASSWD "SysAdmin"
#define SERVICE "VWService0"
#define DOMAIN "IDMIS_SERVER"
#define ORGANIZATION "FileNet"
#define REGION "1"

void interrupt_handler();
int print_return();
int operation_createvoucher();
int operation_correspondence();
int processobject();
void browseloop();
int init();
void quit();
void usage();
extern void exit();

VW_Error error = success;

VW_LogonHandle logonHandle = 0;
VW_QueueHandle queueHandle = 0;
VW_ActiveWPHandle workPerformerHandle = 0;
VW_BrowseHandle browseId = 0;
VW_QueueElementHandle queueElementId = 0;
VW_OperationHandle operationId = 0;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 216

 Server-side Application
Compilation

int aborted = 0;
int verbose = 0;
int loud = 1;
int idleTime = 0;

void interrupt_handler (int i)

{
aborted = 1;
signal (SIGINT, interrupt_handler);
}

int print_return(char* procName, VW_Error error)

{
VW_MessageType message;

if (error)
{
printf("Got an error during %s.\n", procName);
VW_GetErrorMessage(error, message);
printf("The error is: %s \n", message);
return -1;
}
else
if ( verbose )
printf(" %s was successful.\n", procName);

return 0;
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 217

 Server-side Application
Compilation

int operation_createvoucher()
{
char insuredsName[40];
VW_Float claimAmount;

error = VW_GetString(operationId, "soprInsuredsName", insuredsName);

if ( print_return("VW_GetString(soprInsuredsName)", error) < 0)
return -1;

error = VW_GetFloat(operationId, "foprClaimAmount", &claimAmount);

if ( print_return("VW_GetString(foprClaimAmount)", error) < 0)
return -1;

printf("\n\n-------------------------------------------------------------\n");
printf(" PAY THE CLAIM\n\n");
printf(" Pay to the order of: %s\n\n", insuredsName);
printf(" Amount: $%6.2f\n\n\n", claimAmount);
printf("-------------------------------------------------------------\n\n");

}
int operation_correspondence()
{
char insuredsName[40];
char claimNumber[40];
char status[40];

error = VW_GetString(operationId, "soprInsuredsName", insuredsName);

if ( print_return("VW_GetString(soprInsuredsName)", error) < 0)
return -1;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 218

 Server-side Application
Compilation

error = VW_GetString(operationId, "soprClaimNumber", claimNumber);

if ( print_return("VW_GetString(soprClaimNumber)", error) < 0)
return -1;

error = VW_GetString(operationId, "soprStatus", status);

if ( print_return("VW_GetString(soprStatus)", error) < 0)
return -1;

printf("\n\n-------------------------------------------------------------\n");
printf(" CORRESPONDENCE\n\n");
printf(" To: %s\n\n", insuredsName);
printf(" Regarding\n");
printf(" Claim: %s\n\n", claimNumber);
printf(" Disposition\n");
printf(" of Claim: %s\n\n", status);
printf(" Should you have any questions about\n");
printf(" the disposition of this claim please\n");
printf(" contact our claims office at 800/555-3333.\n\n");
printf("-------------------------------------------------------------\n\n");

int processobject()
{
char operationName[20];
int operation = 0;
int failed_operation = 0;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 219

 Server-side Application
Compilation

error = VW_NextWorkObjectToBrowse( browseId, &queueElementId);

if ( print_return("VW_NextWorkObjectToBrowse", error) < 0)
return -1;

error = VW_LockWorkObject(queueElementId, &operationId);

if ( error == F_Err_VW_Svcapi_WobAlreadyLocked )
return 0;
if ( print_return("VW_LockWorkObject", error) < 0)
return -1;

error = VW_GetOperationName(operationId, operationName);

if ( print_return("VW_GetOperationName", error) < 0)
return -1;

if ( strcmp(operationName, "CreateVoucher") == 0 )
operation = 1;
if ( strcmp(operationName, "Correspondence") == 0 )
operation = 2;

switch (operation)
{
case 1:
if ( operation_createvoucher() < 0)
failed_operation = 1;
break;

case 2:
if ( operation_correspondence() < 0)
failed_operation = 1;
break;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 220

 Server-side Application
Compilation

default:
if (loud)
printf("Undefined Operation\n");
failed_operation = 1;
}

if ( failed_operation )
{
error = VW_UnlockWorkObject(operationId);
operationId = 0;
if ( print_return("VW_UnlockWorkObject", error) < 0)
return -1;
}
else
{
error = VW_UnlockAndDispatch(operationId);
operationId = 0;
if ( print_return("VW_UnlockAndDispatch", error) < 0)
return -1;

}
return 0;
}

void browseloop()
{
unsigned long workObjectCount = 0;
int nowork = 0;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 221

 Server-side Application
Compilation

if (loud)
printf("Processing Started\n");

while ( 1 )
{
if (aborted)
quit();

error = VW_BeginBrowsingWorkQueue(workPerformerHandle, &browseId, 10,

&workObjectCount, 0);
if ( print_return("VW_BeginBrowsingWorkQueue", error) < 0)
quit();
if ( workObjectCount == 0 )
nowork = 1;
else
nowork = 0;

while ( workObjectCount-- && aborted == 0 )

{
if ( processobject() < 0 )
quit();
}

if ( browseId )
{ error = VW_EndBrowsingWorkQueue(browseId);
print_return("VW_EndBrowsingWorkQueue", error);
browseId = 0;
}
if ( nowork )
{
if (loud)
printf(" Idle for %d seconds\n", idleTime);
sleep(idleTime * SECONDS);
}
}
August 1998 Panagon Visual WorkFlo Application Developer’s Guide 222
 Server-side Application
Compilation

}
int init(char* UserID, char* Password, char* VWService, VW_IsolatedRegionType Region)
{

if (loud)
{
printf("\nWorkPerformer Initializing\n");
printf(" UserID=%s\n", UserID);
printf(" VWService=%s\n", VWService);
printf(" Region=%d\n\n", Region);
}
error = VW_LogonEx(UserID, Password, VWService, Region, &logonHandle);
if ( print_return("VW_LogonEx", error) < 0)
{
logonHandle = 0;
return -1;
}

error = VW_AttachToWorkQueue(logonHandle, "Unattended", &queueHandle);

if ( print_return("VW_AttachToWorkQueue", error) < 0)
{
queueHandle = 0;
return -1;
}

error = VW_ReportToWork(queueHandle, &workPerformerHandle);

if ( print_return("VW_ReportToWork", error) < 0)
{
workPerformerHandle = 0;
return -1;
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 223

 Server-side Application
Compilation

return 0;
}

void quit ()

{
if ( operationId )
{
error = VW_UnlockWorkObject(operationId);
print_return("VW_UnlockWorkObject", error);
operationId = 0;
}

if ( browseId )
{ error = VW_EndBrowsingWorkQueue(browseId);
print_return("VW_EndBrowsingWorkQueue", error);
browseId = 0;
}

if ( workPerformerHandle )
{ error = VW_LeaveWork(workPerformerHandle);
print_return("VW_LeaveWork", error);
workPerformerHandle = 0;
}

if ( queueHandle )
{ error = VW_DetachFromWorkQueue(queueHandle);
print_return("VW_DetachFromWorkQueue", error);
queueHandle = 0;
}

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 224

 Server-side Application
Compilation

if ( logonHandle )
{ error = VW_Logoff(logonHandle);
print_return("VW_Logoff", error);
logonHandle = 0;
}
exit (1);
}

void help()
{
printf("\nThis program processes the Unattended WorkPerfomer Class\n");
printf("of the Visual WorkFlo AutoClaim demo.\n\n");
printf("It performs two operations:\n");
printf(" Correspondence: Prints a letter to the stdout\n");
printf(" CreateVoucher: Prints a voucher to stdout\n\n");
printf("The program will poll the queue every [i] seconds looking for work.\n");
printf("When work is found in the queue all Work Object will be processed\n");
printf("until the queue is empty.\n\n");
usage();
}

void usage()
{
printf("\nusage: unattended -u [userid] -p [password] -s [VWService]\n");
printf(" -d [domain] -o [organization] -r [region]\n");
printf(" -i [idle polling interval]\n");
printf(" -v verbose mode -q quiet mode -h help\n\n\n");

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 225

 Server-side Application
Compilation

printf("defaults: userid=SysAdmin password=SysAdmin

VWService=VWService0\n");
printf(" domain=IDMIS_SERVER organization=FileNet region=1\n");
printf(" idle polling interval = 10\n\n");
printf("To terminate the program type ^C\n\n");
exit (1);
}

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

{
int i;
char fc;
char userid[20] = USERID;
char passwd[20] = PASSWD;
char service[20] = SERVICE;
char domain[20] = DOMAIN;
char organization[20] = ORGANIZATION;
char region[20] = REGION;
char polling[20] = IDLE_POLLING_INTERVAL;
char vwservice[80] = "";
int iregion;

/* Set Defaults */

signal (SIGINT, interrupt_handler);

for (i = 1; i < argc; i++)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 226

 Server-side Application
Compilation

{
if (aborted)
quit();
fc = argv[i][0];
if (fc == ’-’) /* leading minus is optional */
{
fc = argv[i][1];
if ( fc == NULL )
usage();
}

switch (fc)
{
case ’u’:
if ( (i + 1) == argc )
usage();
strcpy(userid,argv[++i]);
break;
case ’p’:
if ( (i + 1) == argc )
usage();
strcpy(passwd,argv[++i]);
break;
case ’s’:
if ( (i + 1) == argc )
usage();
strcpy(service,argv[++i]);
break;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 227

 Server-side Application
Compilation

case ’d’:
if ( (i + 1) == argc )
usage();
strcpy(domain,argv[++i]);
break;
case ’o’:
if ( (i + 1) == argc )
usage();
strcpy(organization,argv[++i]);
break;
case ’r’:
if ( (i + 1) == argc )
usage();
strcpy(region,argv[++i]);
break;
case ’i’:
if ( (i + 1) == argc )
usage();
strcpy(polling,argv[++i]);
break;
case ’v’:
verbose = 1;
break;
case ’q’:
loud = 0;
break;
case ’h’:
help();
break;

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 228

 Server-side Application
Compilation

default:
usage();
break;
}
}

iregion = atoi(region);
idleTime = atoi(polling);
strcat(vwservice, service);
strcat(vwservice, ":");
strcat(vwservice,domain);
strcat(vwservice,":");
strcat(vwservice,organization);

if ( init(userid, passwd, vwservice, iregion) < 0)

{
quit();
}

browseloop();

Work Performer on HPUX

Develop a server-side active Work Performer to run on the HPUX plat-
form, using the sample applications on the Visual WorkFlo 3.01 CD as
guides.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 229

 Server-side Application
Compilation

Compiler/Runtime Compatibility
Running Work Performers on the HP requires patches for the HP aC++
compiler. Minimum compiler and runtime versions are as follows:

Compiler and Runtime

Compiler Version RuntimeVersion Compatible?
A.01.09 A.01.09 Yes
A.01.12 A.01.12 No
A.01.12 A.01.15 Yes
A.01.15 A.01.15 Yes

There are two samples to run on the HP:

VWSample
Unattended

Procedures follow for using these.

Sample HPUX Work Performer: VWSample

1 Find the following files:

vwsample.cpp
makefile
vwsample.cdl

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 230

 Server-side Application
Compilation

These are on the client PC, where you installed Visual WorkFlo, in this
directory:

Samples\HPUX_Sample\

2 Transfer the step 1 files from the CD, as follows:

• Move these into a directory on the server:

vwsample.cpp
makefile

Use ftp, for example, to transfer them.

• Transfer vwsample.cdl with Visual WorkFlo\Conductor.

See the Predevelopment Checklist, mentioned at the beginning of

this chapter, for context.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 231

 Server-side Application
Compilation

3 For the HP aC++ compiler, use makefile, which you transfered in step
2, as the basis for compilation. The contents of makefile follow:

CC = /opt/aCC/bin/aCC
LD = /opt/aCC/lbin/ld

CLNTSHOBJ = /fnsw/client/shobj

TARGET = vwsample

OBJECTS_LIST = vwsample.o

all : $(TARGET)

$(TARGET) : $(OBJECTS_LIST)
$(CLNTPGMLINK) -o $(TARGET) $(OBJECTS_LIST)

.cpp.o:
$(CC) $(CFLAGS) -D_ANSI_C_SOURCE -z -g -DVW_SERVER -I/fnsw/
client/include -c $<

VW_LAST_LIB = -lvwcppv

VW_CLIENT_LIBS = -lvwalloc \
-lvwfnbase \
-lvwperobj \
-lvwdbi \

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 232

 Server-side Application
Compilation

-lvwexpr \
-lvwsystem \
-lvwruncom \
-lvwrunsvc \
-lvwapi \
-lvwmemry

FN_CLIENT_LIBS = \
-lASH -lBES -lBESr -lCDCD -lCKS -lCOR -lCSM -lCSMr -lDTI \
-lFFI -lFP -lGLO -lINX -lINXD -lINXr -lNCH -lNCHr \
-lNLT -lODF -lPRI -lPRIr -lPRS -lPSI -lQMA -lSC -lSEC -lSECr -lSMM \
-lSQI -lSSU -lSysV -lTPI -lWQS -lI64

CLNTPGMLINK = $(LD) -z /opt/aCC/lib/crt0.o -u ___exit -u main -L /opt/aCC/lib \

/opt/aCC/lib/cpprt0.o \
+b $(CLNTSHOBJ) \
-B immediate \
+vallcompatwarnings \
-L$(CLNTSHOBJ) \
$(FN_CLIENT_LIBS) \
$(VW_CLIENT_LIBS) \
$(CEXE_EXPS) \
/opt/langtools/lib/end.o -lstream -lstd -lCsup -lcl
-lc \
$(VW_LAST_LIB) \
-lm \
/usr/lib/libdld.sl
.SUFFIXES: .cpp .cpp~

clean:
rm -rf $(OBJECTS_LIST) $(TARGET)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 233

 Server-side Application
Compilation

In the line of the above makefile that reads:

TARGET = vwsample

Change vwsample to the name of your Work Performer.

List your source files to the right of the equal sign, in the line of the
makefile that reads:

OBJECTS_LIST = vwsample.o

Your code might look like this, for example:

OBJECTS_LIST = floats.o integers.o mysmple.o

This script uses HP ANSI C++ compiler (aCC), rather than the CC
(cfront) compiler.

4 At the prompt, enter the command: makefile.

This causes the application to use the code in vwsample.cpp to create

an executable. The code in vwsample.cpp begins with the following :

#include <stdio.h>
#include <string.h>

#include <svcapi.h>
#include <stdlib.h>

#define TRUE 1
#define FALSE 0

#define success 0

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 234

 Server-side Application
Compilation

The vwsample.cpp code continues as detailed in Step 6 on page 192,

beginning with the line:

void print_usage(void)

It is a series of procedures, at the end of which is the main routine that

logs onto Visual WorkFlo, uses the procedures, then logs off of Visual
WorkFlo.

Sample HPUX Work Performer: Unattended

1 Find the following files:

unattended.cpp
makefile
unattended

These are on the client PC, where you installed Visual WorkFlo, in this
directory:

Samples\HPUX_Unattended

2 Transfer the step 1 files from the CD into a directory on the server, us-
ing ftp, for example.

3 Transfer AutoClaim.cdl to your server with Visual WorkFlo\Conductor.

This is on the client PC, where you installed Visual WorkFlo, in this di-
rectory:

Samples\AutoClaim\

See the Predevelopment Checklist, mentioned at the beginning of this

chapter, for context.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 235

 Server-side Application
Compilation

4 For the HP aC++ compiler, use makefile, which you transfered in step
2, as the basis for compilation. The contents of makefile follow:

CC = /opt/aCC/bin/aCC
LD = /opt/aCC/lbin/ld

CLNTSHOBJ = /fnsw/client/shobj

TARGET = unattended

OBJECTS_LIST = unattended.o

all : $(TARGET)

$(TARGET) : $(OBJECTS_LIST)
$(CLNTPGMLINK) -o $(TARGET) $(OBJECTS_LIST)

.cpp.o:
$(CC) $(CFLAGS) -D_ANSI_C_SOURCE -z -g -DVW_SERVER -I/fnsw/
client/include -c $<

VW_LAST_LIB = -lvwcppv

VW_CLIENT_LIBS = -lvwalloc \
-lvwfnbase \
-lvwperobj \
-lvwdbi \

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 236

 Server-side Application
Compilation

-lvwexpr \
-lvwsystem \
-lvwruncom \
-lvwrunsvc \
-lvwapi \
-lvwmemry

FN_CLIENT_LIBS = \
-lASH -lBES -lBESr -lCDCD -lCKS -lCOR -lCSM -lCSMr -lDTI \
-lFFI -lFP -lGLO -lINX -lINXD -lINXr -lNCH -lNCHr \
-lNLT -lODF -lPRI -lPRIr -lPRS -lPSI -lQMA -lSC -lSEC -lSECr -lSMM \
-lSQI -lSSU -lSysV -lTPI -lWQS -lI64

CLNTPGMLINK = $(LD) -z /opt/aCC/lib/crt0.o -u ___exit -u main -L /opt/aCC/lib \

/opt/aCC/lib/cpprt0.o \
+b $(CLNTSHOBJ) \
-B immediate \
+vallcompatwarnings \
-L$(CLNTSHOBJ) \
$(FN_CLIENT_LIBS) \
$(VW_CLIENT_LIBS) \
$(CEXE_EXPS) \
/opt/langtools/lib/end.o -lstream -lstd -lCsup -lcl
-lc \
$(VW_LAST_LIB) \
-lm \
/usr/lib/libdld.sl
.SUFFIXES: .cpp .cpp~

clean:
rm -rf $(OBJECTS_LIST) $(TARGET)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 237

 Server-side Application
Compilation

In the line of the above makefile that reads:

TARGET = unattended

Change unattended to the name of your Work Performer.

List your source files to the right of the equal sign, in the line of the
makefile that reads:

OBJECTS_LIST = unattended.o

Your code might look like this, for example:

OBJECTS_LIST = floats.o integers.o mysmple.o

This script uses HP ANSI C++ compiler (aCC), rather than the CC
(cfront) compiler.

5 At the prompt, enter the command: makefile.

This causes the application to use the code in unattended.cpp to

create an executable. The code in unattended.cpp begins as
follows:#include <stdio.h>

#include <stdio.h>
#include <stdlib.h>
#include <ctype.h>
#include <string.h>
#include <signal.h>

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 238

 Server-side Application
Compilation

#ifdef _WIN32
#include <stdlib.h>
#define sleep _sleep
#define SECONDS 1000
#else
#define SECONDS 1
#include <unistd.h>
#endif

#include <svcapi.h>
#include <vwerrors.h>

#define NIL NULL

#ifndef success
#define success 0
#endif

The unattended.cpp code then continues as detailed in Step 7 on

page 215, beginning with the default constants.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 239

 Server-side Application
Topics Common to Server- and Client-side Applications

Topics Common to Server- and Client-side Applications

For the following topics, which apply to applications that run both on
the Visual WorkFlo server and the PC workstation, see the linked top-
ics in the previous chapter of this manual:

“Performance Optimization” on page 181

“Debugging the Application” on page 177

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 240

 4
4Application Programming Interface

An application uses the Visual WorkFlo 3.0 application programming

interface (API) to service Work Objects and queues and manage and
monitor the Visual WorkFlo system. Your application becomes a Visual
WorkFlo application when it does one of the following:

• Accesses the API with Visual WorkFlo Rapid Application Develop-

ment (RAD) controls

Visual WorkFlo installation includes the RAD controls and their

help system contains information on how to use them. Also, see
“Rapid Access Development” on page 66.

• Calls the VW_Logon( ) or the VW_LogonEx( ), then calls subse-

quent functions of the API 1

Calling the API

A Visual WorkFlo application can call the following APIs, which are in
the SVCAPI.H file, in the directory where you installed Visual WorkFlo.

1.VW_Logon( ) and VW_LogonEx( ) are functions of the Application Programming In-

terface. This guide uses the acronym “API” as both the abbreviation for the interface
and to mean a single function of the API, to reflect popular use.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 241

 4 Application Programming Interface
Calling the API

Locator
Click on an API name in the locator table, below, to view the details of
the API.

Return to If you link to an API detail, then wish to return to this locator, scroll to
this Locator the end of the API detail and click on “Locator” .

“VW_AttachToWorkQueue” on Identifies the Work Queue of a Work Per-

page 264 former Class (to which an active Work
Performer, only, belongs)
“VW_BeginBrowsingWork- Establishes a browse session in a spe-
Queue” on page 267 cific Work Queue and reports the num-
ber of Work Objects available in that
queue for browsing
“VW_BindToUser” on page 272 Restricts processing of a Work Object to
the specified user
“VW_BrmCreateBrowseModi- Creates a browse modifier object with
fier” on page 274 which to override the default Work
Queue rules
“VW_BrmFreeBrowseModifier” Frees the resources that were allocated
on page 276 by VW_BrmCreateBrowseModifier( )
“VW_BrmSetLockFilter” on Specifies whether to show locked Work
page 277 Objects in a browse session; overwrites
the effects of previous calls; overrides
default pre-selection rules with a specific
browse modifier object
“VW_BrmSetPreSelectRule” on Enables the developer to specify a pre-
page 279 selection rule in the browse modifier ob-
ject
“VW_BrmSetSelectRule” on Enables the developer to specify a se-
page 281 lection rule in the browse modifier object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 242

 4 Application Programming Interface
Calling the API

“VW_BrmSetPreSelectRule” on Enables the developer to specify a pre-

page 279 selection rule in the browse modifier ob-
ject
“VW_BrmSetSelectRule” on Enables the developer to specify a se-
page 281 lection rule in the browse modifier object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 243

 4 Application Programming Interface
Calling the API

“VW_FreeAccessHandle” on Frees the resources allocated by a call to

page 300 VW_WobQueryGetAccessHandle or
VW_GetAccessHandle( )
“VW_FreeArrayPtr” on page 303 Frees the array allocated by VW_GetAr-
rayPtr( )
(DLL wrapper interface)
“VW_GetAccessHandle” on Returns a Work Object access handle to
page 304 use in calling data access APIs, then in
changing the Work Object
“VW_GetArray” on page 307 Returns either the value of a parameter
of the Operation processing the Work
Object or a specific field value in a Work
Performer, a queue, or a Work Object
(OLE Automation interface)
“VW_GetArrayPtr” on page 309 Returns either the value of a parameter
of the Operation processing the Work
Object or a specific field value in a Work
Performer, a queue, or a Work Object
(DLL wrapper interface)
“VW_GetArraySize” on page 312 Returns the size of an array before you
call VW_GetArrayPtr( )
“VW_GetBindings” on page 314 Returns the name of the user to whom a
Work Object is bound and the machine
ID of the user’s workstation
“VW_GetBoolean” on page 316 Returns a parameter value that is of type
boolean
“VW_GetClassFieldNames” on Returns (1) a list of the names of all data
page 318 fields of a Work Class or Work Performer
Class and (2) the number of these data
field names
“VW_GetDataType” on page 320 Returns the Visual WorkFlo data type of
a field or parameter

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 244

 4 Application Programming Interface
Calling the API

“VW_GetDataTypeArray” on Returns the data type of an array’s ele-

page 322 ments
“VW_GetErrorMessage” on Returns the message text that corre-
page 324 sponds to an error code that an API has
returned
“VW_GetErrorMessageSize” on Returns (as status, rather than output)
page 325 the size of an error message string
“VW_GetField” on page 326 Returns the value of a field, the size of
which you determined by first calling
VW_GetFieldSize( )
“VW_GetFieldNames” on Returns the names and number of pa-
page 330 rameters or fields of an object
“VW_GetFieldSize” on page 332 Returns the size, in bytes, of the value
requested by VW_GetField( )
“VW_GetFloat” on page 334 Returns a parameter value that is of type
double
“VW_GetFPNumber” on Returns a parameter value that is of type
page 336 16-byte decimal floating-point
“VW_GetHandleType” on Returns a handle’s type
page 338
“VW_GetInteger” on page 339 Returns a parameter value that is of type
integer
“VW_GetIsolatedRegion” on Identifies the isolated region in which
page 340 you are working
“VW_GetMachineId” on Indicates which workstation you are
page 341 logged onto
“VW_GetOperationName” on Returns the name of the next Operation
page 342 that will process a Work Object (call after
you call VW_GetOperationNameSize( ),
so you will know the amount of space to
allocate)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 245

 4 Application Programming Interface
Calling the API

“VW_GetOperationNameSize” Returns the size of an Operation name,

on page 343 to be called before VW_
GetOperationName( ) to determine the
amount of space to allocate for the re-
turned name
“VW_GetParameterMode” on Returns the direction (in, out, or in and
page 344 out) of an operation parameter or a field
“VW_GetQueueNames” on Returns the names and number of
page 346 queues in the Online repository
“VW_GetString” on page 348 Returns a parameter value that is of type
string, after you call VW_GetStringSize(
) to determine the amount of space to al-
locate for it
“VW_GetStringSize” on Returns the size of a string, before you
page 350 call VW_GetString( ), to determine the
amount of space to allocate for the string
“VW_GetTime” on page 352 Returns a parameter value that is of type
time
“VW_GetWobSignature” on Returns the signature that uniquely iden-
page 354 tifies a Work Object in the VWService
“VW_GetWorkClassNames” on Lists the names and number of Work
page 355 Classes in the Online repository—either
all or specific Work Classes
“VW_GetWorkObjectLockSta- Indicates whether a Work Object is
tus” on page 357 locked and, if it is locked, the machine ID
of the workstation on which it is locked
“VW_GetWorkObjectName” on Returns the Work Object name, the hu-
page 359 man-readable-string equivalent of the
Work Object tag

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 246

 4 Application Programming Interface
Calling the API

“VW_GetWorkPerformerClass- Lists the names and number of Work

Names” on page 361 Performer Classes that are in the Online
repository—either all or specific Work
Performer Classes
“VW_GetWorkPerformerHan- Returns a handle for an active Work Per-
dle” on page 364 former
“VW_GetWorkQueueDepth” on Returns the number of Work Objects (in-
page 365 cluding locked and bound Work Objects)
that are in a specific Work Queue or a
System Queue
“VW_LeaveWork” on page 366 Frees the resources allocated by VW_
ReportToWork( )
“VW_LockWorkObject” on Locks a Work Object so the caller can
page 367 perform the current Operation
“VW_LogMessage” on page 370 Logs a user-defined message for a spe-
cific event logging option
“VW_Logoff” on page 372 Frees resources allocated by VW_
Logon( )
“VW_Logon” on page 373 At the PC workstation, logs the user onto
a VWService and provides access to the
isolated region defined in the VW.INI file
Establishes an application as a WorkFlo
application
Compare this with VW_LogonEx( ), be-
low.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 247

 4 Application Programming Interface
Calling the API

“VW_LogonEx” on page 376 At the server or PC workstation, logs the

user onto the FileNET domain and a
VWService
Enables the user to specify the VWSer-
vice and isolated region within the
VWService as input
Allows the user to run more than one ap-
plication in more than one VWService
and/or in more than one isolated region
Establishes an application as a Visual
WorkFlo application
Compare this with VW_Logon( ), above.
“VW_LogQueryBegin” on Creates and initializes a query session
page 381 on log records
“VW_LogQueryEnd” on Ends a log query session and releases
page 383 system resources allocated by VW_
LogQueryBegin( )
“VW_LogQueryNextRecords” on Returns log records one at a time, in a
page 384 block up to your specified maximum, or
all at once
“VW_NextWorkObject- Returns a handle to a Work Object in a
ToBrowse” on page 388 browsed queue
“VW_QQueryBegin” on Starts a query in a queue by returning a
page 390 queue query handle
The query reads data for one or more
Work Objects, according to your param-
eter specifications. You have the option
of locking Work Objects in the same step
that you query them, thereby optimizing
performance.
“VW_QQueryEnd” on page 398 Ends a queue query session and re-
leases system resources allocated to the
query

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 248

 4 Application Programming Interface
Calling the API

“VW_QQueryNextLocked- Returns a handle to the Operation that

WorkObject” on page 399 will process the next Work Object, which
returned in the batch queried by VW_
QQueryBegin( )
Call this API, rather than VW_QQueryN-
extWorkObject( ), if you locked the Work
Object with VW_QQueryBegin( ).
“VW_QQueryNextWorkObject” Returns a handle with which to query
on page 401 about the next Work Object in a queue
The handle is to the next Work Object in
the batch queried by VW_
QQueryBegin( ). Call this API, rather
than VW_QQueryNextLockedWorkOb-
ject( ), if you did not lock the Work Object
with VW_QQueryBegin( ).
“VW_QsCreateQuerySpecifier” Returns a query specifier handle to use
on page 403 in retrieving records
This query specifier is a set of conditions
that selects a group of records based on
the range of an index key and filter con-
ditions.
“VW_QsFreeQuerySpecifier” on Frees a query specifier, releasing its re-
page 414 sources
“VW_QueueGetStats” on Returns statistics on a queue of Work
page 415 Objects
“VW_RaiseException” on Causes an exception-handling Instruc-
page 419 tion Sheet to execute (to be used when
you wish to reject the values in a Work
Object’s data fields)
“VW_ReportToWork” on Establishes a Visual WorkFlo application
page 421 as a Work Performer, after a previous
call to VW_AttachToWorkQueue( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 249

 4 Application Programming Interface
Calling the API

“VW_RosterGetStats” on Returns statistics on a roster

page 423
“VW_SequencedWait” on Controls the number of sequenced mode
page 428 Work Object data in workstation memory
and minimizes transaction between
workstation and server
“VW_SequencedWobFetch” on Returns an operation handle for a locked
page 437 Work Object if there is a locked Work
Object in sequenced mode during the
specified period
Returns nil if there is none
“VW_SetArray” on page 439 Sets values into a specified field (for OLE
Automation interface)
“VW_SetArrayPtr” on page 441 Sets values into a specified field (for C
interface)
“VW_SetBoolean” on page 444 Sets a value of type boolean into a field
“VW_SetField” on page 446 Sets the value of a field, given the field
name and object to which the field be-
longs
“VW_SetFloat” on page 448 Sets a value of type double into a field
“VW_SetFPNumber” on Sets a value of type 16-byte decimal
page 450 floating point into a field
“VW_SetInteger” on page 452 Sets a value of type integer into a field
“VW_SetString” on page 454 Sets a value of type string into a field
“VW_SetTime” on page 456 Sets a value of type time into a field
“VW_TerminateWorkObject” on Terminates the Work Object that a Work
page 458 Performer is processing
“VW_UnBind” on page 460 Ends the binding restrictions placed on a
Work Object by VW_BindToUser

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 250

 4 Application Programming Interface
Calling the API

“VW_UnlockAndDispatch” on Unlocks a Work Object, updates it with

page 461 operation parameters that have returned
from data access APIs, and dispatches it
to the next Work Queue
“VW_UnlockWorkObject” on Unlocks a Work Object, discards any op-
page 462 eration parameters that have returned
from data access APIs, and leaves the
Work Object in the Work Queue, un-
changed since VW_LockWorkObject( )
locked it.
“VW_WobQueryCreate” on Creates a query handle to use in obtain-
page 463 ing information about Work Objects that
are in a specific Work Class or that are in
a specific Work Class and have a spe-
cific Work Object ID value
“VW_WobQueryEnd” on Frees the resources allocated by VW_
page 468 WobQueryCreate( )
“VW_WobQueryExecute” on Executes the Work Object query associ-
page 469 ated with the query handle created by
VW_WobQueryCreate( )
Matches and counts Work Objects up to
your specified maximum
(Use the resulting batch index number to
find information about a specific Work
Object.)
“VW_WobQueryGetAccessHan- Returns an access handle to use in
dle” on page 472 changing a Work Object, with a call to a
data access API
“VW_WobQueryGetWorkObject- Returns the Work Object name, the hu-
Name” on page 475 man-readable-string equivalent of the
Work Object tag, using an index the de-
veloper obtained by calling VW_
WobQueryCreate( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 251

 4 Application Programming Interface
Calling the API

“VW_WobQueryInstrSheet” on Returns the name of the Instruction

page 477 Sheet that Visual WorkFlo is executing
to process a specific Work Object
“VW_WobQueryOperation” on Returns the name of the Operation that
page 479 will next process a Work Object
“VW_WobQueryWorkPerformer- Returns the name of the Work Performer
Class” on page 481 Class of a specific Work Object
(Use it to learn which Work Queue has
the Work Object of interest.)

Calling Sequence
The order in which an application calls APIs depends on its category,
as follows. The chart, “API Calling Sequence” on page 484 shows the
sequence.

Calling Sequence Chart

Application Category Purpose Path Color
Creative Create and dispatch a Blue
Work Object
Administrative Locate a Work Object, Green
administer a Work Ob-
ject, and prepare reports
Active Work Performer Process a Work Object, Red
executing Instructions
on the Instruction Sheet
that is associated with
the Work Object’s Work
Class

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 252

 4 Application Programming Interface
Functional Groups

Functional Groups
The developer typically uses APIs in groups that are associated by
task.

API Pairs
Always call the following APIs as a pair. The first of the pair allocates
Visual Workflo resources for the task and the second frees these re-
sources when the task is complete:

VW_LogonEx( )
VW_Logoff( )

VW_Logon( )
VW_Logoff( )

VW_CreateWorkObject( )
VW_DispatchWorkObject( )

VW_WobQueryCreate( )
VW_WobQueryEnd( )

VW_QsCreateQuerySpecifier( )
VW_QsFreeQuerySpecifier( )

VW_QQueryBegin( )
VW_QQueryEnd( )

VW_LogQueryBegin( )
VW_LogQueryEnd( )

VW_WobQueryGetAccessHandle( )
VW_WobQueryFreeAccessHandle( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 253

 4 Application Programming Interface
Functional Groups

VW_AttachToWorkQueue( )
VW_DetachFromWorkQueue( )

VW_ReportToWork( )
VW_LeaveWork( )

VW_BrmCreateBrowseModifier( )
VW_BrmFreeBrowseModifier( )

VW_BeginBrowsingWorkQueue( )
VW_EndBrowsingWorkQueue( )

VW_GetAccessHandle( )
VW_FreeAccessHandle( )

VW_LockWorkObject( )
VW_UnlockWorkObject( )

VW_GetArraySize( ) and VW_GetArrayPtr( )

VW_FreeArrayPtr( )

API Association by Task Group

Visual WorkFlo provides services, such as Work Object creation,
queue handling, exception handling, and work sequencing, via the
APIs, which the developer uses in the following task groups. See “Lo-
cator” on page 242 for the overview of a specific API or a link to its de-
tails.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 254

 4 Application Programming Interface
Functional Groups

Logon and Logoff

Your application must log on to browse queues and to find, lock, and
create Work Objects. It logs off to free the resources Visual WorkFlo
allocated when it logged on.

VW_LogonEx
VW_Logon
VW_Logoff

Work Object Creation

Call the following to create a Work Object and dispatch it to a Work
Queue.

VW_CreateWorkObject
VW_DispatchWorkObject

Logging
Use these logging APIs to develop and debug applications:

VW_LogMessage
VW_LogQueryBegin
VW_LogQueryNextRecords
VW_LogQueryEnd

Consider processing time and space when calling these APIs with an
application that runs daily.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 255

 4 Application Programming Interface
Functional Groups

Statistics
Call the following for statistics:

VW_QueueGetStats Statistics on a queue of Work Objects in

a specific Work Class or on Work Per-
formers in a specific Work Performer
Class
VW_RosterGetStats Statistics on the roster of Work Objects
in a specific Work Class

Sequenced Mode
Call these APIs to use sequenced mode processing, minimizing trans-
action between the PC workstation and server:

VW_SequencedWait
VW_Call
VW_SequencedWobFetch

Queue Handling
Use the following APIs to:

• Browse a Work Queue (to find a Work Object)

• Lock the Work Object so that you can process it

or
Unlock the Work Object

VW_AttachToWorkQueue Call this, then call

VW_ReportToWork( ), to start an
active Work Performer.
VW_BeginBrowsingWorkQueue

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 256

 4 Application Programming Interface
Functional Groups

VW_BrmCreateBrowseModifier To browse a Work Queue in an or-

der that differs from the default,
follow these guidelines:
1) Call this API to create a browse
modifier object that overrides the
rules defined in the Work Per-
former Class associated with the
Work Queue. (See the Visual
WorkFlo/Composer Handbook for
information on Work Queue rules.)
2) Call one of the three APIs that
immediately follows in this list.
3) Call VW_BeginBrowsingWork
Queue( ), passing a handle to the
browse modifier object as a pa-
rameter, to apply your new rules.
VW_BrmSetLockFilter Specifies whether to show locked
Work Objects in a browse session
VW_BrmSetPreSelectRule Visual Workflo evaluates the pre-
selection rule on the server when
it browses the Work Queue.
VW_BrmSetSelectRule Visual Workflo evaluates the se-
lection rule on the client, when it
browses the Work Queue, after
the server completes processing.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 257

 4 Application Programming Interface
Functional Groups

VW_BrmSetSortRules If no sort expression specifies a

Work Performer field, the client
evaluates sort rules before insert-
ing them.

If no sort expression specifies a

Work Performer field and there is
no sort browse modifier, the server
sorts when browsing.

If a sort expression specifies a

Work Performer field or there is a
sort browse modifier, the client
processes the sort rules during the
browse, after Visual Workflo evalu-
ates the selection rules.
VW_BrmFreeBrowseModifier Call this, any time after calling
VW_
BeginBrowsingWorkQueue( ), to
free the resources associated with
the browse modifier object.
VW_DetachFromWorkQueue Call this, after calling
VW_LeaveWork( ), to shut down
an active Work Performer.
VW_EndBrowsingWorkQueue
VW_LeaveWork Call this, then call
VW_DetachFromWorkQueue( ), to
shut down an active Work Per-
former.
VW_LockWorkObject
VW_NextWorkObjectToBrowse

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 258

 4 Application Programming Interface
Functional Groups

VW_ReportToWork Call this, after calling

VW_AttachToWorkQueue( ), to
start an active Work Performer.
VW_UnlockWorkObject
VW_UnlockAndDispatch

Work Object Access

Use the following to get or free a Work Object access handle (the pa-
rameter name is WobAccessHandle). Use WobAccessHandle in calls
to APIs that set data (see “Data Access” on page 260) to change the
Work Object.

VW_FreeAccessHandle
VW_GetAccessHandle
VW_WobQueryGetAccessHandle

Work Object Binding

Use the following to restrict processing of a Work Object to the work-
station of a specific user and to release this restriction:

VW_BindToUser
VW_GetBindings
VW_UnBind

Work Object Information

Use the following to find a Work Object:

VW_WobQueryCreate
VW_WobQueryExecute

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 259

 4 Application Programming Interface
Functional Groups

VW_WobQuery
WorkPerformerClass
VW_WobQueryOperation
VW_WobQueryInstrSheet
VW_WobQueryEnd

Call these APIs to obtain the following:

• Name of the next Operation that is to process a Work Object

• Handle of the Work Performer that is processing a Work Object

• Signature of a Work Object

VW_GetOperationName
VW_GetOperationNameSize
VW_GetWorkPerformerHandle
VW_GetWobSignature

Data Access
Use the following to get or set the values in:

• A Work Object data field

• An Operation parameter

• A Work Queue field

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 260

 4 Application Programming Interface
Functional Groups

• A Work Performer data field

VW_FreeArrayPtr
VW_GetArrayPtr
VW_GetArraySize
VW_GetBoolean
VW_GetDataType
VW_GetDataTypeArray
VW_GetFloat
VW_GetInteger
VW_GetString
VW_GetStringSize
VW_GetTime
VW_SetArrayPtr
VW_SetBoolean
VW_SetFloat
VW_SetInteger
VW_SetString
VW_SetTime

Error Handling
Call the following to handle exceptions while an application runs:

VW_CheckVersionCompatibility
VW_CurrentException
VW_GetErrorMessageSize
VW_GetErrorMessage

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 261

 4 Application Programming Interface
API Detail Content

VW_RaiseException
VW_TerminateWorkObject

API Detail Content

The following sample illustrates API detail content.

Details also include the following:

• Examples

• Sources of related information

• Link to the API Locator, an alphabetized list of the APIs, which in-
cludes an overview of each API and a link to its details

Application syntax, such as data type, depends on the interface you

use (see “Syntax” on page 45 for details).

The APIs
The details of each Visual WorkFlo API follow.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 262

 4 Application Programming Interface
The APIs

API name ErrorCode = VW_SampleDetail (LogonHandle, DeveloperName, NumberOfDollars)

Source of input parameter
Visual Basic
Object Browser
Usage phrase,
Input/Output Data Type Source/Destination
parameter order for
applications that LogonHandle long VW_LogonEx( )
interface directly with or
the OLE server Output bold VW_Logon( )
Developer supplies DeveloperName string Developer Output destination
all input shown bold
in italics
NumberOfDollars double VW_RetireEarly( )
Center column displays the
Link to API See “API Calling Sequence” on page 10 for context. data type you see for an API
parameter when you open the
calling sequence
Visual Basic 5.0 Object Browser
chart

Summary of the This API returns the amount of money you have in your savings account.
result of making
the call

This API returns in NumberOfDollars the amount of money in an account, given the
Result of Call account holder’s name, which you supply in the string, DeveloperName.

Tip Use the output of this API as input to the VW_RetireEarly( ) API, to determine whether
you may give notice at the office.

C typedef is the
parameter data
type in an
typedef VW_Error(VWAPIENTRY* VW_SampleDetailProcType)
application that
uses the OLE (VW_LogonHandle,
wrapper DLL or VW_AccountNameType,
the DLL adaptor VW_Float FAR *);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 263

 4 Application Programming Interface
The APIs

VW_AttachToWorkQueue
ErrorCode = VW_AttachToWorkQueue (LogonHandle, QueueName,
QueueHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

QueueName string Developer

QueueHandle long VW_ReportToWork( )

or
VW_ReportToWork( )
and
VW_
BrmCreateBrowseModifier( )
VW_BrmCreateBrowse-
Modifier( )

See “API Calling Sequence” on page 484 for context.

Summary This API identifies one of the following:

• Work Queue of a Work Performer Class

This is for an active Work Performer, only.

• System Queue

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 264

 4 Application Programming Interface
VW_AttachToWorkQueue

Result of Call Upon calling this API, a Visual WorkFlo application becomes a active
Work Performer. This API returns QueueHandle, which identifies the
Work Queue of the Work Performer Class to which an active Work
Performer belongs or the System Queue you name in the
string, QueueName .

Note Visual WorkFlo enhancements have caused this API’s functionality to

outpace its name; it now identifies System Queues as well as Work
Queues.

Tips Call this (once for each queue you wish to browse) when you start an
active Work Performer.

Call VW_DetachFromWorkQueue( ) to release the resources associ-

ated with QueueHandle.

C typedef typedef VW_Error(VWAPIENTRY* VW_AttachToWorkQueueProcType)

(VW_LogonHandle,
VW_ClassNameType,
VW_QueueHandle FAR *);

Example

OLE with Visual Basic

See “OLE with Visual Basic” on page 269 for an example in conjunc-
tion with a call to VW_BeginBrowsingWorkQueue.

See Also:
“VW_BrmCreateBrowseModifier” on page 274

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 265

 4 Application Programming Interface
VW_AttachToWorkQueue

“VW_DetachFromWorkQueue” on page 297

“VW_ReportToWork” on page 421

“VW_WobQueryCreate” on page 463 for comparison

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 266

 4 Application Programming Interface
VW_BeginBrowsingWorkQueue

VW_BeginBrowsingWorkQueue
ErrorCode = VW_BeginBrowsingWorkQueue (WorkPerformerHandle,
MaxWorkObjectCount, BrowseModifierHandle, BrowseSessionHan-
dle, WorkObjectCount)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WorkPerformerHandle long VW_ReportToWork( )

BrowseSessionHandle long VW_

NextWorkObjectToBrowse( )
VW_
EndBrowsingWorkQueue( )

MaxWorkObjectCount long Developer

WorkObjectCount long

BrowseModifierHandle long VW_BrmCreate

BrowseModifier( )

See “API Calling Sequence” on page 484 for context.

Summary This API establishes a browse session in a specific Work Queue and
reports the number of Work Objects available in that queue for
browsing.

Result of Call Browsing follows default or modified Work Queue rules. This API re-
turns the following:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 267

 4 Application Programming Interface
VW_BeginBrowsingWorkQueue

• BrowseSessionHandle

- Establishes a browse session in the Work Queue of the Work

Performer identified by WorkPerformerHandle

- Carries forward, as input to a subsequent call, any information

that came in on the browse modifier object, BrowseModifier-
Handle, regarding override of a Work Queue’s default rules

An earlier call to VW_BrmCreateBrowseModifier( ), returns

BrowseModifierHandle to override default browsing rules. Oth-
erwise, BrowseModifierHandle is empty and browsing follows
default rules.

• WorkObjectCount:

This is the number of Work Objects available in the specified Work

Queue during the browse session.

WorkObjectCount < MaxWorkObjectCount

Where:

MaxWorkObjectCount is the number you provide to specify the

maximum number of Work Objects to browse.

Minimize the overrun of system resources by limiting the number of

Work Objects to be browsed. (If you set MaxWorkObjectCount to
zero, no limit is defined before browsing begins.)

Tips A call to this API takes a snapshot of the queue; subsequent change in
the queue is not reflected in results from associated VW_
BeginBrowsingWorkQueue( ) calls.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 268

 4 Application Programming Interface
VW_BeginBrowsingWorkQueue

When you finish browsing the Work Queue, call VW_End-

BrowsingWorkQueue( ) to free the associated resources.

The returned BrowseSesionHandle remains valid until there is a call to

VW_EndBrowsingWorkQueue( ) or VW_LeaveWork( ).

C typedef typedef VW_Error(VWAPIENTRY VW_BeginBrowsingWorkQueueProcType)

(VW_ActiveWPHandle,
unsigned long,
VW_BrowseHandle FAR *,
unsigned long FAR *,
VW_BrModHandle);

Example

OLE with Visual Basic

Below is sample code to call this API and APIs that precede and
follow it:

Dim LogonHandle As Long

Dim WorkQueueHandle As Long
Dim WorkPerformerHandle As Long
Dim BrowseSessionHandle As Long
Dim QueueElementHandle As Long
Dim MaxWorkObjectCount as Long
Dim WorkObjectCount as Long

ErrorCode = VWServer.VW_Logon(LogonHandle)
If ErrorCode <> 0 Then
Error handling code
End If
ErrorCode = VWServer.VW_AttachToWorkQueue ( _

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 269

 4 Application Programming Interface
VW_BeginBrowsingWorkQueue

LogonHandle, _
"WPClass", _
WorkQueueHandle)
If ErrorCode <> 0 Then
Error handling code
End If
ErrorCode = VWServer.VW_ReportToWork ( _
WorkQueueHandle, _
WorkPerformerHandle)

If ErrorCode <> 0 Then

Error handling code
End If

MaxWorkObjectCount = 1
ErrorCode = VWServer.VW_BeginBrowsingWorkQueue( _
WorkPerformerHandle, _
BrowseSessionHandle, _
MaxWorkObjectCount, _
WorkObjectCount, _
BrowseModifierHandle)
If WorkObjectCount = 0 Then
MsgBox "There are no available Work Objects in
the queue."
End
End If
If ErrorCode <> 0 Then
Error handling code
End If

ErrorCode = VWServer.VW_NextWorkObjectToBrowse( _
BrowseSessionHandle, _

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 270

 4 Application Programming Interface
VW_BeginBrowsingWorkQueue

QueueElementHandle)
If ErrorCode <> 0 Then
Error handling code
End If

See Also:
“VW_BrmCreateBrowseModifier” on page 274

“VW_EndBrowsingWorkQueue” on page 299

“VW_NextWorkObjectToBrowse” on page 388

“VW_QQueryBegin” on page 390 for comparison

“VW_ReportToWork” on page 421

“Visual WorkFlo Work Object Creation” on page 56 for sample code

that calls VW_LogonEx( ) rather than VW_Logon( )

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 271

 4 Application Programming Interface
VW_BindToUser

VW_BindToUser
ErrorCode = VW_BindToUser (Handle, UserName)

Visual Basic
Object Browser
Input Data Type Source
Handle, as one of these: long
OperationHandle VW_LockWorkObject( )

WobAccessHandle VW_WobQueryGetAccess
Handle
or
VW_GetAccessHandle

UserName string Developer

See “API Calling Sequence” on page 484 for context.

Summary This API restricts processing of a Work Object to a specific user.

Result of Call This API restricts processing of the Work Object identified by Handle to
the user whose name you specify in UserName in one of the following
ways:

• Three-part user name as a string literal

For example, “JDoe:MyServer:MyCompany”

• String expression that evaluates to a three-part user name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 272

 4 Application Programming Interface
VW_BindToUser

For example, the name of a Work Class field that holds a three-part
user name (It must meet the general guidelines for expressions;
see Composer help for details.)

• Empty string("")

This causes the Work Object to bind to the next user that accesses
it. (Compare this with binding to a machine.)

Tip If the Work Object identified by Handle is in sequenced mode, Visual

WorkFlo removes it from sequenced mode and sends it to the Malfunc-
tion Instruction Sheet.

C typedef typedef VW_Error(VWAPIENTRY *VW_BindToUserProcType)

(VW_Handle,
VW_UserNameType FAR);

See Also:
“VW_GetAccessHandle” on page 304

“VW_LockWorkObject” on page 367

“VW_SequencedWait” on page 428

“VW_WobQueryGetAccessHandle” on page 472

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 273

 4 Application Programming Interface
VW_BrmCreateBrowseModifier

VW_BrmCreateBrowseModifier
ErrorCode = VW_BrmCreateBrowseModifier (QueueHandle, Browse-
ModifierHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QueueHandle long VW_AttachToWorkQueue( )

BrowseModifierHandle long VW_

BeginBrowsingWorkQueue( )
VW_
BrmFreeBrowseModifier( )
VW_BrmSetLockFilter( )
VW_BrmSetPreSelectRule( )
VW_BrmSetSelectRule( )
VW_BrmSetSortRules( )

See “API Calling Sequence” on page 484 for context.

Summary This API creates a browse modifier object with which to override the
default Work Queue rules.

Result of Call This API uses Work Queue identification in QueueHandle to return the
browse modifier object, BrowseModifierHandle.

Browse modifier objects are independent of Work Performers and

browse sessions and can override a Work Queue’s default rules. After
you call this API, call one of these to specify override of the default
rules:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 274

 4 Application Programming Interface
VW_BrmCreateBrowseModifier

VW_BrmSetPreSelect-Rule( )

VW_BrmSetSelectRule( )

VW_BrmSetSortRules( )

VW_BrmSetLockFilter( )

Call VW_BeginBrowsingWorkQueue( ) to apply the modified rules.

Tips Call VW_BrmFreeBrowseModifier( ) to free the resources allocated by

this API, at any time after calling the VW_BeginBrowsingWorkQueue( )
API.

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmCreateBrowseModifierProcType)

(VW_QueueHandle,
VW_BrModHandle FAR *);

See Also:
The Visual WorkFlo/Composer Handbook for more information about
the rules and allowable expressions

“VW_BeginBrowsingWorkQueue” on page 267

“VW_BrmFreeBrowseModifier” on page 276

“VW_BrmSetLockFilter” on page 277

“VW_BrmSetPreSelectRule” on page 279

“VW_BrmSetSelectRule” on page 281

“VW_BrmSetSortRules” on page 283

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 275

 4 Application Programming Interface
VW_BrmFreeBrowseModifier

VW_BrmFreeBrowseModifier
ErrorCode = VW_BrmFreeBrowseModifier (BrowseModifierHandle)

Visual Basic
Object Browser
Input Data Type Source
BrowseModifierHandle long VW_
BrmCreateBrowseModifier( )

See “API Calling Sequence” on page 484 for context.

Summary This API frees the resources that were allocated by VW_BrmCreate-
BrowseModifier( ) for the browse modifier object.

Result of Call This API frees the resources that were allocated by VW_BrmCreate-
BrowseModifier( ) for the browse modifier object identified by Browse-
ModifierHandle. It invalidates BrowseModifierHandle and has no effect
on previously started browse sessions that used the same modifier ob-
ject.

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmFreeBrowseModifierProcType)

(VW_BrModHandle);

See Also:
The Visual WorkFlo/Composer Handbook for more information about
rules and allowable expressions

“VW_BrmCreateBrowseModifier” on page 274

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 276

 4 Application Programming Interface
VW_BrmSetLockFilter

VW_BrmSetLockFilter
ErrorCode = VW_BrmSetLockFilter (BrowseModifierHandle,
LockFilter)

Visual Basic
Object Browser
Input Data Type Source
BrowseModifierHandle long VW_
BrmCreateBrowseModifier( )

LockFilter long Developer

See “API Calling Sequence” on page 484 for context.

Result of Call This API specifies whether to show locked Work Objects in the browse
session identified by BrowseModHandle. Provide in LockFilter a filter
type that enables you to view locked objects, as follows:

LockFilter setting Result

VW_FILTER_NORMAL Locked Work Objects do not display.
VW_FILTER_WITH-LOCK Locked Work Objects display.

Each call to this API overwrites the effect of previous calls. It overrides
default pre-selection rules only when BrowseModifierHandle identifies
a specific browse modifier object.

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmSetLockFilterProcType)

(VW_BrModHandle,
VW_LockFilterType LockFilter);

Tips This API does not return locked Work Objects only.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 277

 4 Application Programming Interface
VW_BrmSetLockFilter

See Also:
The Visual WorkFlo/Composer Handbook for more information about
rules and allowable expressions

“VW_BrmCreateBrowseModifier” on page 274

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 278

 4 Application Programming Interface
VW_BrmSetPreSelectRule

VW_BrmSetPreSelectRule
ErrorCode = VW_BrmSetPreSelectRule (BrowseModifierHandle, Pre-
SelectionRuleExpression)

Visual Basic
Object Browser
Input Data Type Source
BrowseModifierHandle long VW_
BrmCreateBrowseModifier( )

PreSelectionRule string Developer

Expression

See “API Calling Sequence” on page 484 for context.

Summary This API enables the developer to specify one of the following in a
browse modifier object:

Override the default pre-selection rule

Ignore the default pre-selection rule

Use the default pre-selection rule

You can call it repeatedly to overwrite the effect of previous calls.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 279

 4 Application Programming Interface
VW_BrmSetPreSelectRule

Result of Call This API enables the developer to specify with the string, PreSelection-
RuleExpression, one of the following in the browse modifier object
identified by BrowseModifierHandle:

Input to PreSelectionRuleExpression Result

Your new expression The expression you input overrides the
default pre-selection rule when you
have called this API against a specific
browse modifier object.
It overrides the effect of previous calls
and any default pre-selection rule.
An empty string (“ “) This API ignores the default pre-selec-
tion rule.
A nil pointer This API uses the default pre-selection
rule.

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmSetPreSelectRuleProcType)

(VW_BrModHandle,
char FAR *);

See Also:
The Visual WorkFlo/Composer Handbook for more information about
the pre-selection rule and allowable expressions

“VW_BrmCreateBrowseModifier” on page 274

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 280

 4 Application Programming Interface
VW_BrmSetSelectRule

VW_BrmSetSelectRule
ErrorCode = VW_BrmSetSelectRule (BrowseModifierHandle, Selec-
tionRuleExpression)

Visual Basic
Object Browser
Input Data Type Source
BrowseModifierHandle long VW_
BrmCreateBrowseModifier( )

SelectionRuleExpression string Developer

See “API Calling Sequence” on page 484 for context.

Summary This API enables the developer to specify one of the following in a
browse modifier object:

Override the default selection rule

Ignore the default selection rule

Use the default selection rule

You can call it repeatedly to overwrite the effect of previous calls.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 281

 4 Application Programming Interface
VW_BrmSetSelectRule

Result of Call This API enables the developer to specify with the string, SelectionRu-
leExpression , one of the following in the browse modifier object identi-
fied by BrowseModifierHandle:

Input to SelectionRuleExpression Result

Your new expression The expression you input overrides the
default selection rule when you have
called this API against a specific
browse modifier object.
It overrides the effect of previous calls
and any default selection rule.
An empty string (“ “) This API ignores the default selection
rule.
A nil pointer This API uses the default selection
rule.

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmSetSelectRuleProcType)

(VW_BrModHandle,
char FAR *);

See Also:
The Visual WorkFlo/Composer Handbook for more information about
the selection rule and allowable expressions

“VW_BrmCreateBrowseModifier” on page 274

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 282

 4 Application Programming Interface
VW_BrmSetSortRules

VW_BrmSetSortRules
ErrorCode = VW_BrmSetSortRules (BrowseModifierHandle, Sort
RuleCount, SortRuleExpressions[ ])

Visual Basic
Object Browser
Inputa Data Type Source
BrowseModifierHandle long VW_
BrmCreateBrowseModifier( )

SortRuleCount integer Developer

SortRuleExpression[ ] Developer
a. In an application that uses the OLE wrapper DLL, input the addi-
tional parameter, SortRuleLengths[ ]. Direct OLE server interface
uses the SAFEARRAY (see “Direct Interface with the OLE Server”
on page 47 for more information).

See “API Calling Sequence” on page 484 for context.

Summary This API enables the developer to specify a set of sort rules, such as
one of the following, in a browse modifier object:

Override the default sort rules

Ignore the default sort rules

Use the default sort rules

You can call it repeatedly to overwrite the effect of previous calls.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 283

 4 Application Programming Interface
VW_BrmSetSortRules

Result of Call This API enables the developer to specify with the array, SortRuleEx-
pressions[], one of the following sets of sort rules in the browse modi-
fier object identified by BrowseModifierHandle:

Input to SortRuleExpressions[ ] Result

Your new expressions The expressions you input override the
default sort rules when you have called
this API against a specific browse
modifier object.
It overrides the effect of previous calls
and any default sort rules.
An empty string (“ “) This API ignores the default sort rules.
A nil pointer This API uses the default sort rules.

State the number of expressions in the array, in SortRuleCount and, if

you are using the OLE wrapper DLL, input the length of each expres-
sion1 in SortRuleLengths[].

The browse modifier object identified by BrowseModifierHandle carries

your sort rules forward into browsing.

Tips To override the default sort rules, you must call this API against a spe-
cific browse modifier object—you must have previously called VW_
BrmCreateBrowseModifier( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_BrmSetSortRulesProcType)

(VW_BrModHandle,
unsigned int,

1.The SortRuleLengths[] array must have an entry for each entry in SortRuleExpres-
sions[].

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 284

 4 Application Programming Interface
VW_BrmSetSortRules

char FAR * FAR [ ],

unsigned int FAR [ ]);

Example

OLE with Visual Basic

Following sample code uses the VW_BrmSetSortRules( ) API.

Private Sub Form_Load( )

Dim VWApiSrv As Object

Dim SortRules As Variant
Dim SortRuleLengs As Variant
Dim logonId As Long
Dim wqId As Long
Dim wpId As Long
Dim browseId As Long
Dim browseCount As Long
Dim brModHandle As Long
Dim qeId As Long
Dim wpName As String

wpName = "VBCalc"

ReDim SortRules(0) As String

ReDim SortRuleLengs(0) As Integer

SortRules(0) = "SerialNumber"
SortRuleLengs(0) = 40

Set VWApiSrv = CreateObject("VWApi.Srv")

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 285

 4 Application Programming Interface
VW_BrmSetSortRules

ErrorCode = VWApiSrv.VW_Logon(logonId)
ErrorCode = VWApiSrv.VW_AttachToWork-
Queue(logonId, wpName, wqId)
ErrorCode = VWApiSrv.VW_ReportToWork(wqId, wpId)

ErrorCode = VWApiSrv.VW_BrmCreateBrowseModi-
fier(wqId, brModHandle)
ErrorCode = VWApiSrv.VW_BrmSetSortRules(brModHan-
dle, SortRules, SortRuleLengs)
ErrorCode = VWApiSrv.VW_BeginBrowsingWork-
Queue(wpId, browseId, 0, browseCount,
➥brModHandle)
ErrorCode = VWApiSrv.VW_NextWorkObject-
ToBrowse(browseId, qeId)
ErrorCode = VWApiSrv.VW_EndBrowsingWork-
Queue(browseId)

ErrorCode = VWApiSrv.VW_LeaveWork(wpId)
ErrorCode = VWApiSrv.VW_DetachFromWorkQueue(wqId)
ErrorCode = VWApiSrv.VW_Logoff(logonId)

End Sub

See Also:
The Visual WorkFlo/Composer Handbook for more information about
sort rules and allowable expressions

“VW_BrmCreateBrowseModifier” on page 274

“Direct Interface with the OLE Server” on page 47 if your C/C++ appli-
cation interfaces directly with the OLE server

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 286

 4 Application Programming Interface
VW_BrmSetSortRules

“Visual WorkFlo Work Object Creation” on page 56 for sample code

that calls VW_LogonEx( ) rather than VW_Logon( )

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 287

 4 Application Programming Interface
VW_Call

VW_Call
ErrorCode = VW_Call (OperationHandle, InstructionSheetName )

Visual Basic
Object Browser
Input Data Type Source
OperationHandle long VW_LockWorkObject( )

InstructionSheetName string Developer

See “API Calling Sequence” on page 484 for context.

Summary This API causes Visual WorkFlo to execute a specified Instruction

Sheet. After Visual WorkFlo completes the specified Instruction Sheet,
it returns to the original Instruction Sheet at a point determined by the
final Instruction in the specified Instruction Sheet.

Call this API, rather than VW_RaiseException( ), when you wish to

save the values in a Work Object’s data fields while making sequenc-
ing flexible.

Result of Call This API causes Visual WorkFlo to follow the steps of the Instruction
Sheet you specify in InstructionSheetName in processing the Work
Object from the Work Performer Operation identified by
OperationHandle.

After Visual WorkFlo completes the specified Instruction Sheet work

steps, it returns to the original Instruction Sheet steps at a point deter-
mined by the final Instruction in the specified Instruction Sheet.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 288

 4 Application Programming Interface
VW_Call

Comparison with the Call System Instruction

Use VW_Call( ) as you would use the Call system Instruction. (See the
Visual WorkFlo Composer Handbook for information about the Call
system Instruction.)

Comparison with VW_RaiseException( )

VW_Call( ) is also like VW_RaiseException( ) in that they both:

• Cause Visual WorkFlo to follow the steps of another Instruction

Sheet in processing the Work Object

• Call the exception handling Instruction Sheet immediately, thereby

invalidating OperationHandle and unlocking the Work Object

However, Visual WorkFlo processing differs, as follows:

VW_Call( ) VW_RaiseException( )
Saves changes made to the Work Disregards changes made to the
Object data fields Work Object data fields
Preserves timers (both active and in- Disables all active timers
active)
Leaves a Work Object that is in se- Causes a Work Object that is in se-
quenced mode in that mode quenced mode to exit that mode
Records nothing in the log table Logs an event in the log table if the
event logging option Work Object
Exception is enabled

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 289

 4 Application Programming Interface
VW_Call

Return to Original Instruction Sheet

The final Instruction of your specified Instruction Sheet determines the
return destination of the Work Object processing, as follows:

Final Instruction Destination upon return

on specified Instruction Sheet to original Instruction Sheet
Return = true Same Instruction—the Work Per-
former that called VW_Call( )
Return = false (default) Next Instruction—the Instruction that
follows the Work Performer that
called VW_Call( )
Stop Next Instruction—the Instruction that
follows the Work Performer that
called VW_Call( )

C typedef typedef VW_Error(VWAPIENTRY VW_CallProcType)

(VW_Handle,
VW_InstrSheetNameType FAR);

See Also:
“VW_LockWorkObject” on page 367

“VW_RaiseException” on page 419 for comparison

The Visual WorkFlo/Composer Handbook for information on the Call

and Return system Instructions

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 290

 4 Application Programming Interface
VW_CheckVersionCompatibility

VW_CheckVersionCompatibility
ErrorCode = VW_CheckVersionCompatibility (MajorVersionNumber,
MinorVersionNumber, CurrentMajorVersionNumber, CurrentMinorVer-
sionNumber)

Visual Basic
Object Browser
Input/Output Data Type Source
MajorVersionNumber long Developer

MinorVersionNumber long Developer

CurrentMajorVersion long
Number

CurrentMinorVersion long
Number

See “API Calling Sequence” on page 484 for context.

Summary This API checks that the version of your APIs is compatible with the
current version of APIs.

Result of Call This API returns the current major and minor version numbers in Cur-
rentMajorVersionNumber and CurrentMinorVersionNumber, re-
spectively. You must allocate sufficient memory to accommodate
these.

This provide values with which to compare the major and minor version
numbers of the APIs you are using, MajorVersionNumber and Minor-
VersionNumber, respectively.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 291

 4 Application Programming Interface
VW_CheckVersionCompatibility

If the major version number of your APIs is different from that returned
or if the minor version number of your APIs is less than that returned,
the versions are incompatible.

Tips For correct comparison of minor version numbers, supply a two-digit

number for the APIs you are using. The minor version number that re-
turns in CurrentVersionNumber is, then, a two-digit number. For exam-
ple, the minor version number for release 1.21 is 21 and for release
1.3, it is 30.

C typedef typedef VW_Error(VWAPIENTRY *VW_CheckVersionCompatibilityProcType)

(VW_MajorVersionType,
VW_MinorVersionType,
VW_MajorVersionType FAR *,
VW_MinorVersionType FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 292

 4 Application Programming Interface
VW_CreateWorkObject

VW_CreateWorkObject
ErrorCode = VW_CreateWorkObject (LogonHandle, WorkClassName,
NewWorkObjectHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

WorkClassName string Developer

NewWorkObjectHandle long A set data APIa

VW_DispatchWorkObject( )
a. An API such as VW_SetInteger( ).

See “API Calling Sequence” on page 484 for context.

Summary This API creates a Work Object of a specified Work Class, using the
default data field values set in the class definition.

Result of Call This API creates a Work Object of the Work Class you specify in the
string, WorkClassName, using these:

• Initial field values, set during Work Class definition

• LogonHandle

It is more efficient to call VW_LogonEx( )or VW_Logon( ) once,

then save the returned LogonHandle for use in subsequent calls to

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 293

 4 Application Programming Interface
VW_CreateWorkObject

VW_CreateWorkObject( ) than it is to repeatedly call VW_

LogonEx( ) or VW_Logon( ), then VW_Logoff( ), for a new Logon-
Handle each time.

Note The name “WorkObject” was a valid entry for the WorkClassName in-
put parameter in previous Visual WorkFlo releases. However, it is no
longer valid.

This API returns the ID, NewWorkObjectHandle, for the newly created
Work Object and begins the following series of calls, associated with
Work Object Applications:

VW_CreateWorkObject( )

VW_SetXXX( )

VW_DispatchWorkObject( )

Tips Calling VW_DispatchWorkObject( ) dispatches the newly created Work

Object to the first queue that the Instruction Sheet in its Work Class
definition specifies. Free the resources associated with LogonHandle,
after you have made all calls to this series, by calling VW_Logoff( ).

C typedef typedef VW_Error (VWAPIENTRY *VW_CreateWorkObjectProcType)

(VW_LogonHandle,
VW_ClassNameType,
VW_NewWorkObjectHandle FAR *);

See Also:
“VW_DispatchWorkObject” on page 298

“VW_SetInteger” on page 452 for a sample VW_SetXXX API

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 294

 4 Application Programming Interface
VW_CurrentException

VW_CurrentException
ErrorCode = VW_CurrentException (OperationHandle, ExceptionDe-
scriptor)

Visual Basic
Object Browser
Input/Output Data Type Source
OperationHandle long AVW_LockWorkObject( )

ExceptionDescriptor string

See “API Calling Sequence” on page 484 for context.

Summary This API returns the name of the most recently raised exception and a
text description of the exception condition.

C Syntax ErrorCode = VW_CurrentException (VW_Handle OperationHandle,

VW_ExceptionDescriptor FAR* ExceptionDescriptor)

Result of Call This API names and describes in ExceptionDescriptor the most re-
cently raised exception, identified by OperationHandle, which returned
to an active Work Performer that called VW_LockWorkObject( ).

The string, ExceptionDescriptor, is a structured parameter; it in-

cludes the name and text description, respectively, of the most recently
called exception handling Instruction Sheet and the exception condi-
tion, as follows:

#define VW_MAXEXCEPTIONNAMELEN];
#define VW_MAXEXCEPTIONDESCLEN];
typedef struct

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 295

 4 Application Programming Interface
VW_CurrentException

{
char Name[VW_MAXEXCEPTIONNAMELEN];
char Desc[VW_MAXEXCEPTIONDESCLEN];
} VW_ExceptionDescriptor;

Tips Allocate space for the returned ExceptionDescriptor.

C typedef typedef VW_Error(VWAPIENTRY *VW_CurrentExceptionProcType)

(VW_Handle,
VW_ExceptionDescriptor FAR *);

See Also:
“VW_LockWorkObject” on page 367

“VW_RaiseException” on page 419 to compare exception naming and

description

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 296

 4 Application Programming Interface
VW_DetachFromWorkQueue

VW_DetachFromWorkQueue
ErrorCode = VW_DetachFromWorkQueue (QueueHandle)

Visual Basic
Object Browser
Input Data Type Source
QueueHandle long VW_AttachToWorkQueue( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API frees the resources that were allocated by VW_AttachToWork
Queue( ) for the queue identified by QueueHandle. It invalidates any
further use of QueueHandle.

Call it once for each queue browsed, before the Work Performer shuts
down.

C typedef typedef VW_Error(VWAPIENTRY *VW_DetachFromWorkQueueProcType)

(VW_QueueHandle);

See Also:
“VW_AttachToWorkQueue” on page 264

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 297

 4 Application Programming Interface
VW_DispatchWorkObject

VW_DispatchWorkObject
ErrorCode = VW_DispatchWorkObject (NewWorkObjectHandle)

Visual Basic
Object Browser
Input Data Type Source
NewWorkObjectHandle long VW_CreateWorkObject( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API dispatches the new Work Object, identified by NewWorkOb-
jectHandle, to the first queue that the Instruction Sheet in its Work
Class definition specifies. Always call it after calling VW_
CreateWorkObject( ).

Call it only from an active Work Performer or an administration applica-

tion.

C typedef typedef VW_Error(VWAPIENTRY *VW_DispatchWorkObjectProcType)

(VW_NewWorkObjectHandle);

See Also:
“VW_CreateWorkObject” on page 293

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 298

 4 Application Programming Interface
VW_EndBrowsingWorkQueue

VW_EndBrowsingWorkQueue
ErrorCode = VW_EndBrowsingWorkQueue (BrowseSessionHandle)

Visual Basic
Object Browser
Input Data Type Source
BrowseSessionHandle long VW_
BeginBrowsingWorkQueue( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API frees the resources that were allocated to BrowseSession-
Handle by a call to VW_BeginBrowsingWorkQueue( ). It invalidates
BrowseSessionHandle and any associated QueueElementHandle.
However, it neither releases nor invalidates an Operation handle ob-
tained during the browse session associated with BrowseSessionHan-
dle.

C typedef typedef VW_Error(VWAPIENTRY *VW_EndBrowsingWorkQueueProcType)

(VW_BrowseHandle);

See Also:
“VW_BeginBrowsingWorkQueue” on page 267

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 299

 4 Application Programming Interface
VW_FreeAccessHandle

VW_FreeAccessHandle
ErrorCode = VW_FreeAccessHandle (WobAccessHandle, SaveUp-
dates, SkipCurrentInstruction, Reserved)

Visual Basic
Object Browser
Input Data Type Source
WobAccessHandle long VW_WobQueryGetAccess
Handle( )
or
VW_GetAccessHandle( )

SaveUpdates integer Developer

SkipCurrentInstruction integer Developer

Reserved a string

a. For future use

See “API Calling Sequence” on page 484 for context.

Summary This API frees the resources allocated by a call to one of the following
APIs:

VW_WobQueryGetAccessHandle( )

VW_GetAccessHandle( )

You can set its input to unlock a Work Object in a queue.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 300

 4 Application Programming Interface
VW_FreeAccessHandle

Result of Call This API frees the resources allocated to the handle
WobAccessHandle. You will have set the value of the handle in a previ-
ous call to VW_GetAccessHandle( ) or VW_WobQuery GetAccess-
Handle( ) to unlock a Work Object in a queue or not, as follows:

LockForUpdate was set to true LockForUpdate was set to false

SaveUpdates = true SaveUpdates has no effect and Vi-
causes Visual WorkFlo to save up- sual WorkFlo discards updates to
dates to the Work Object the Work Object.
SaveUpdates = false
causes Visual WorkFlo to discard
updates to the Work Object
SkipCurrentInstruction = true SkipCurrentInstruction has no effect.
causes Visual WorkFlo to set the In-
struction that is processing the Work
Object identified by WobAccess-
Handle to ‘completed’ and to send
the Work Object to the WorkQueue
of the next Instruction
SkipCurrentInstruction = false
has no effect

Call VW_FreeAccessHandle( ) only from an active work Performer or

an administration application.

C typedef typedef VW_Error(VWAPIENTRY *VW_FreeAccessHandleProcType)

(VW_WobQueryHandle,
VW_Boolean
VW_Boolean
VW_InstrSheetNameType);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 301

 4 Application Programming Interface
VW_FreeAccessHandle

See Also:
“VW_GetAccessHandle” on page 304

“VW_WobQueryGetAccessHandle” on page 472

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 302

 4 Application Programming Interface
VW_FreeArrayPtr

VW_FreeArrayPtr
An application that uses the OLE wrapper DLL uses this API, rather
than VW_FreeArray( ).

Visual Basic
Object Browser
Input/Output Data Type Source
ArrayPointer Not applicable VW_GetArrayPtr ( )
VW_GetFieldNames( )
NumberOfElements VW_GetClassFieldNames( )
ArrayType Developer

Result of Call This API frees the array to which ArrayPointer points. (If ArrayPointer is
of type string, for example, this API frees all string elements in the ar-
ray.)

C typedef typedef VW_Error(VWAPIENTRY *VW_FreeArrayPtrProcType)

(VW_ArrayPtrType FAR *,
long,
VW_DataType);

See Also:
“VW_GetArrayPtr” on page 309

“VW_GetClassFieldNames” on page 318

“VW_GetFieldNames” on page 330

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 303

 4 Application Programming Interface
VW_GetAccessHandle

VW_GetAccessHandle

ErrorCode = VW_GetAccessHandle (QueueElementHandle, LockFor

Update, WobAccessHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QueueElementHandle long VW_
NextWorkObjectToBrowse( )

LockForUpdate integer Developer

WobAccessHandle long VW_GetWobSignature( )

VW_BindToUser( ), VW_
GetBindings( ), and VW_
UnBind( )
VW_GetXXX( ) and VW_
SetXXX( )a
VW_FreeAccessHandle( )
a. The XXX in VW_GetXXX( ) and SetXXX( ) is a data type, such as
in VW_SetInteger( ).

See “API Calling Sequence” on page 484 for context.

Summary This API returns a Work Object access handle that Visual WorkFlo
uses in making subsequent calls to the data access 1 APIs, then in
changing the Work Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 304

 4 Application Programming Interface
VW_GetAccessHandle

Result of Call This API returns the handle WobAccessHandle to use in subsequent
calls to the data access APIs, then, in changing the Work Object identi-
fied by QueueElementHandle.

A security error returns unless the logged-on user has access rights to
Work Object and the queue. Results of the setting choice for Lock
ForUpdate follow:

LockForUpdate = true LockForUpdate = false

This API locks the Work Object in The Work Object remains unlocked
the queue. and the returned WobAccessHan-
dle can be used only to read data
fields from the Work Object.
The user has read and write access The user has read-only access to
to both Work Object and queue. Work Object and queue.
Subsequent attempts to obtain an
access handle for the locked Work
Object fail until WobAccessHandle
is freed.

Tips After locking a Work Object with this API, verify that it still fits the
search criteria you specified while locating it; the Work Object may
change between the time you find it and the time you lock it.

Call VW_FreeAccessHandle( ) to free the resources allocated by

this API.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetAccessHandleProcType)

(VW_QueueElementHandle,

1.The data access APIs are those such as VW_GetInteger( ) and VW_SetFloat( ).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 305

 4 Application Programming Interface
VW_GetAccessHandle

VW_Boolean,
VW_WobAccessHandle FAR *);

See Also:
Visual WorkFlo Installation and Administration Handbook for informa-
tion on Work Object and queue access

“VW_BindToUser” on page 272

“VW_FreeAccessHandle” on page 300

“VW_GetBindings” on page 314

“VW_GetWobSignature” on page 354

“VW_NextWorkObjectToBrowse” on page 388

“VW_UnBind” on page 460

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 306

 4 Application Programming Interface
VW_GetArray

VW_GetArray
ErrorCode = VW_GetArray (Handle, FieldName, DataType, Array( ))

Visual Basic
Object Browser
Input/Output Data Typea Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

DataType long Developer

Array( ) VARIANT
FAR*
a. If your application uses the OLE wrapper DLL, rather than inter-
faces directly with the OLE server, please see “VW_GetArrayPtr”
on page 309.

See “API Calling Sequence” on page 484 for context.

Summary This API returns in an array either the value of a parameter of the Op-
eration that is processing a Work Object or a specific field value from
one of the following:

Active Work Performer

Work Queue or System Queue

Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 307

 4 Application Programming Interface
VW_GetArray

This is for the OLE Automation interface; so, it is not necessary to call
VW_GetArraySize( ) before calling this API and VW_FreeArrayPtr( )
after it.

Result of Call This API returns in Array( ) the value of a field or parameter in an ob-
ject1 identified by Handle, as shown in the following table. Provide, in
FieldName, the name of the field for which you seek the value.

Value that returns in the array,

Handle as specified in FieldName
WorkPerformerHandle Active Work Performer data field
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field

Please supply the data type of the array elements in DataType. Possi-
ble values for this integer type parameter are:

0 Integer

1 Float

2 String

3 Boolean

4 Time

C typedef Not applicable

1.This is an object in the general sense, rather than a Work Object, specifically.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 308

 4 Application Programming Interface
VW_GetArrayPtr

VW_GetArrayPtr
Applications that use the OLE wrapper DLL call this API. If your appli-
cation interfaces directly with the OLE server, please see “VW_GetAr-
ray” on page 307.

Visual Basic
Object Browser
Input/Output Data Typea Source
Handle Not applicable See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName Developer

DataType Developer

Array( )
NumberOfElements
a. If your application interfaces directly with the OLE server, rather
than uses the OLE wrapper DLL, please see “VW_GetArray” on
page 307.

See “API Calling Sequence” on page 484 for context.

Summary This API returns in an array either the value of a parameter of the Op-
eration that is processing the Work Object or a specific field value from
one of the following:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 309

 4 Application Programming Interface
VW_GetArrayPtr

Active Work Performer

Work Queue
Work Object

It also returns the number of elements in the array. Before you call it,
call VW_GetArraySize( ); afterwards, free the array pointer with a call
to VW_FreeArrayPtr( ).

Result of Call This API returns in ArrayPointer the value of a field or parameter in an
object 1 identified by Handle, as shown in the following table. Provide, in
FieldName, the name of the field for which you seek the value and, in
DataType, the data type of the field’s data.

Value that returns in the array pointer,

Handle as specified in FieldName
WorkPerformerHandle Active Work Performer data field
QueueElementHandle Work Queue field
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field

VW_GetArrayPtr( ) also returns in NumberOfElements the number of

elements in the array.

Tips This API, rather than the caller, allocates the necessary memory and
returns the array pointer to the caller. If the returned array is of type
string, then the array elements are of type VW_String.

1.This is an object in the general sense, rather than a Work Object, specifically.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 310

 4 Application Programming Interface
VW_GetArrayPtr

C typedef typedef VW_Error(VWAPIENTRY *VW_GetArrayPtrProcType)

(VW_Handle,
VW_FieldNameType,
VW_ArrayPtrType FAR *,
long FAR *,
VW_DataType);

See Also:
“VW_FreeArrayPtr” on page 303

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 311

 4 Application Programming Interface
VW_GetArraySize

VW_GetArraySize
Call this API to use the C-language OLE wrapper DLL in obtaining the
size of an array before calling VW_GetArrayPtr( ).

Visual Basic
Object Browser
Input/Output Data Typea Source
Handle Not applicable See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName Developer

NumberOfElements
a. If your application interfaces directly with the OLE server, rather
than uses the OLE wrapper DLL, please see “VW_GetArray” on
page 307.

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in NumberOfElements the number of elements in an

array that is the field or parameter you specify with FieldName.

Call this API to obtain the size of an array before calling VW_
GetArrayPtr( ).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 312

 4 Application Programming Interface
VW_GetArraySize

Handle indicates which object1 the field or parameter name is in, as

follows:

Handlea Array
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name
a.See “Handle” on page 50 for the various sources and types of Handle.

Tips Call VW_FreeArrayPtr( ) to free the returned array.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetArraySizeProcType)

(VW_Handle,
VW_FieldNameType
long FAR *);

See Also:
“VW_FreeArrayPtr” on page 303

“VW_GetArrayPtr” on page 309

Return to “Locator” on page 242

1.This is an object in the general sense, rather than a Work Object, specifically.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 313

 4 Application Programming Interface
VW_GetBindings

VW_GetBindings
ErrorCode = VW_GetBindings (Handle, UserName, MachineId)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

UserName string

MachineId string

See “API Calling Sequence” on page 484 for context.

Summary This API returns the name of the user to whom a Work Object is bound
and the ID of the workstation to which the Work Object is bound.

Result of Call This API returns in UserName the name of the user to whom the Work
Object (identified by Handle, below) is bound and, in MachineId, the
ID of the workstation to which that Work Object is bound, as follows:

Handle Work Object identifier

QueueElementHandle Work Queue field
OperationHandle Parameter in the current Operation
WobAccessHandle Work Object data field

C typedef typedef VW_Error(VWAPIENTRY *VW_GetBindingsProcType)

VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 314

 4 Application Programming Interface
VW_GetBindings

VW_UserNameType FAR,
VW_MachineIdType FAR);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 315

 4 Application Programming Interface
VW_GetBoolean

VW_GetBoolean
ErrorCode = VW_GetBoolean (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value integer

See “API Calling Sequence” on page 484 for context.

Summary This API returns a parameter value that is of type boolean.

Result This API returns in Value a parameter value that is of type boolean.
Specify in FieldName the field or parameter name in the object identi-
fied by Handle, for which you seek the boolean value, as follows:

Handle Value
WorkPerformerHandle Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter in the current Operation
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_GetBooleanProcType)

(VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 316

 4 Application Programming Interface
VW_GetBoolean

VW_FieldNameType
VW_Boolean FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 317

 4 Application Programming Interface
VW_GetClassFieldNames

VW_GetClassFieldNames
ErrorCode = VW_GetClassFieldNames (LogonHandle, ClassName,
ArrayPointer)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

ClassName string Developer

Array Variant

ArrayPointer Not applicable VW_FreeArrayPtr( )

NumberOfElements Not applicable VW_FreeArrayPtr( )

See “API Calling Sequence” on page 484 for context.

Summary This API lists the names of data fields in a specific Work Class or Work
Performer Class and, for the C interface, the number of data field
names in the class.

Result of Call This API returns strings in the array Array or ArrayPointer, each of
which is the name of a data field in the class you specify in Class-
Name.

For the C interface, it also returns in NumberOfElements the number

of data fields in the class.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 318

 4 Application Programming Interface
VW_GetClassFieldNames

Tips This API allocates memory for the pointer; you must free it with VW_
FreeArrayPtr( ). (Provide VW_STRINGTYPE as the ArrayType input
parameter in that call.)

C typedef typedef VW_Error(VWAPIENTRY *VW_GetClassFieldNamesProcType)

(VW_Handle,
VW_ClassNameType FAR
VW_ArrayPtrType FAR *
long FAR *);

See Also:
“VW_FreeArrayPtr” on page 303

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 319

 4 Application Programming Interface
VW_GetDataType

VW_GetDataType
ErrorCode = VW_GetDataType (Handle, FieldName, FieldType)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

FieldType long

See “API Calling Sequence” on page 484 for context.

Summary This API returns the Visual WorkFlo data type of a field or parameter.

Result of Call This API returns in FieldType a parameter value that is the type of
data in the field you specify in FieldName. It can be one of the follow-
ing:

0 Integer
1 Float
2 String
3 Boolean
4 Time
5 Array
6 Variant
7 Variant array

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 320

 4 Application Programming Interface
VW_GetDataType

The field belongs to the object identified by Handle, as follows:

Handle Field for which data type is returned

WorkPerformerHandle Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter in the current Operation
NewWorkObjectHandle Name of a data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_GetDataTypeProcType)

(VW_Handle,
VW_FieldNameType,
VW_DataType FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 321

 4 Application Programming Interface
VW_GetDataTypeArray

VW_GetDataTypeArray
ErrorCode = VW_GetDataTypeArray (Handle, FieldName, FieldType)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

FieldType long

See “API Calling Sequence” on page 484 for context.

Summary This API returns the data type of an array’s elements.

Result of Call This API returns in FieldType a parameter value that indicates the
data type of the elements in the array that is the field you specify in
FieldName. The field belongs to the object identified by Handle, as fol-
lows:

Handle Field for which data type is returned

WorkPerformerHandle Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter in the current Operation
NewWorkObjectHandle Name of a data field in a new
Work Object
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 322

 4 Application Programming Interface
VW_GetDataTypeArray

C typedef typedef VW_Error(VWAPIENTRY *VW_GetDataTypeArrayProcType)

(VW_Handle,
VW_FieldNameType,
VW_DataType FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 323

 4 Application Programming Interface
VW_GetErrorMessage

VW_GetErrorMessage
ErrorCode = VW_GetErrorMessage (ErrorCode, ErrorMessage)

Visual Basic
Object Browser
Input/Output Data Type Source
ErrorCode long API calls that have an error

ErrorMessage string

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in ErrorMessage the error message text that corre-
sponds to the code in ErrorCode. ErrorMessage is a pointer to a writ-
able location in memory.

Status (Return This is the number of bytes that copy to ErrorMesssage, excluding the
Value) null character. Zero returns if ErrorCode is not valid.

Tips Call VW_GetErrorMessageSize( ) to determine the amount of memory

you must allocate for the error message string.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetErrorMessageProcType)

(VW_Error,
VW_MessageType FAR);

See Also:
“VW_GetErrorMessageSize” on page 325

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 324

 4 Application Programming Interface
VW_GetErrorMessageSize

VW_GetErrorMessageSize
ErrorCode = VW_GetErrorMessageSize (ErrorCode)

Visual Basic
Object Browser
Input Data Type Source
ErrorCode long API calls that have an error

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns (in the status return value, below, rather than as out-
put) the size of the error message string that corresponds to the code
in ErrorCode. Before calling VW_GetErrorMessage( ), call this to de-
termine the amount of memory you must allocate for the string.

Status (Return This is the number of bytes that copy to ErrorMesssage (see “VW_
Value) GetErrorMessage” on page 324), excluding the null character. Zero re-
turns if ErrorCode is not valid.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetErrorMessageSizeProcType)

(VW_Error);

See Also:
“VW_GetErrorMessage” on page 324

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 325

 4 Application Programming Interface
VW_GetField

VW_GetField
ErrorCode = VW_GetField (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value string

See “API Calling Sequence” on page 484 for context.

Summary This API returns the value of a specific field.

From an application that uses the OLE wrapper DLL, call it after you
call VW_GetFieldSize( ) so that you know the amount of memory to al-
locate for the field value.

Result of Call This API returns in the string Value the value of a field you identify in
FieldName. The field belongs to the object identified by Handle, as fol-
lows:

Handle Value returned

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 326

 4 Application Programming Interface
VW_GetField

Handle Value returned

NewWorkObjectHandle Name of a data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

To return the name of a system field, input one of the queue or log field
names listed below to FieldName.

Queue field:

F_WobNum
F_WorkSpaceId
F_Locked
F_LockMachine
F_LockUser
F_LockTime
F_BindPending
F_BoundUser
F_BoundMachine
F_Tag
F_UniqueId
F_OperationId
F_WorkClassId
F_EnqueueTime
F_CreateTime
F_InstrSheetId
F_WorkOrderId
F_SortOrder
F_Operation
F_WorkObjectName
F_Class

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 327

 4 Application Programming Interface
VW_GetField

This API can return the value of any of the above system fields, but
do not input the highlighted fields to the QuerySpecifierIndexKey
parameter in a previous call to VW_QsCreateQuerySpecifier( ).
(Visual WorkFlo automatically appends F_UniqueId to the index
key.)

Log field:

F_WobNum
F_SeqNumber
F_UserId
F_EventType
F_PermWorkSpaceId
F_TempWorkSpaceId
F_WorkObjectNumber
F_WorkClassId
F_ParentWorkObjNum
F_MachineId
F_WPClassId
F_WPOperationId
F_InstrSheetId
F_AuthWorkOrderId
F_Duration
F_WorkObjectTag
F_Text

Tips From an application that uses the OLE wrapper DLL, call VW_
GetFieldSize( ) before calling this API, to learn the amount of memory
you must allocate for the returned string.

C typedef typedef VW_Error (VWAPIENTRY *VW_GetFieldProcType)

(VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 328

 4 Application Programming Interface
VW_GetField

VW_FieldNameType,
VW_String);

See Also:
“VW_GetFieldSize” on page 332

“VW_QsCreateQuerySpecifier” on page 403 for details on

the QuerySpecifierIndexKey input parameter

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 329

 4 Application Programming Interface
VW_GetFieldNames

VW_GetFieldNames
ErrorCode = VW_GetFieldNames (Handle, FieldNames)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.
FieldNames Variant
ArrayPointer Not applicable VW_FreeArrayPtr( )

NumberOfElements Not applicable VW_FreeArrayPtr( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns strings in the array FieldNames or the array Array-
Pointer (in the case of an application that uses the OLE wrapper DLL)
each of which is the name of a parameter or field in the object identi-
fied by Handle, as follows:

Names of the fields or parameters of

Handle this object return in an array
WorkPerformerHandle Active Work Performer
QueueElementHandle Work Queue
OperationHandle Operation processing the Work Object
WobAccessHandle Work Object

It returns the number of fields the object has in NumberOfElements

for the OLE wrapper DLL interface.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 330

 4 Application Programming Interface
VW_GetFieldNames

Tips For applications that use the OLE wrapper DLL, this API allocates
memory for ArrayPointer, but you must free the array by calling VW_
FreeArrayPtr( ) when you no longer need it. (Provide VW_STRING-
TYPE to that API as the ArrayType input parameter.)

C typedef typedef VW_Error(VWAPIENTRY *VW_GetFieldNamesProcType)

(VW_Handle,
VW_ArrayPtrType FAR *,
long FAR *);

See Also:
“VW_FreeArrayPtr” on page 303

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 331

 4 Application Programming Interface
VW_GetFieldSize

VW_GetFieldSize
ErrorCode = VW_GetFieldSize (Handle, FieldName, Size)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Size long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in the string Size the size (in bytes) of the value in the
field you specify in FieldName. The field belongs to the object identified
by Handle, as follows:

Handle Size of this field

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

Call this API before calling VW_GetField( ) to determine the amount of

memory you must allocate for the field value returned by that API.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 332

 4 Application Programming Interface
VW_GetFieldSize

C typedef typedef VW_Error (VWAPIENTRY *VW_GetFieldSizeProcType)

(VW_Handle,
VW_FieldNameType,
unsigned int FAR *);

See Also:
“VW_GetField” on page 326

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 333

 4 Application Programming Interface
VW_GetFloat

VW_GetFloat
ErrorCode = VW_GetFloat (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value double

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Value a parameter value that is of type double. It
returns the data as a 16-byte, floating-point decimal.

Specify in FieldName the field or parameter name in the object identi-

fied by Handle, for which you seek the double value, as follows:

Handle Field
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_GetFloatProcType)

(VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 334

 4 Application Programming Interface
VW_GetFloat

VW_FieldNameType
VW_Float FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 335

 4 Application Programming Interface
VW_GetFPNumber

VW_GetFPNumber
ErrorCode = VW_GetFPNumber (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Value a parameter value that is of type floating
point. It returns the data as a 16-byte, floating-point decimal. It differs
from VW_GetFloat (see “VW_GetFloat” on page 334), in that it re-
quires WorkFlo Application Libraries.

Specify in FieldName the field or parameter name in the object identi-

fied by Handle, for which you seek the floating-point value, as follows:

Handle Field
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 336

 4 Application Programming Interface
VW_GetFPNumber

C typedef typedef VW_Error(VWAPIENTRY *VW_GetFPNumberProcType)

(VW_Handle,
VW_FieldNameType
VW_FPNumber);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 337

 4 Application Programming Interface
VW_GetHandleType

VW_GetHandleType
ErrorCode = VWServer.VW_GetHandleType (Handle, HandleType)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

HandleType long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in HandleType the type of the handle identified by the
input Handle.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetHandleTypeProcType)

(VW_Handle,
VW_HandleType FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 338

 4 Application Programming Interface
VW_GetInteger

VW_GetInteger
ErrorCode = VW_GetInteger (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Value a parameter value that is of type integer.
Specify in FieldName the field or parameter name in the object identi-
fied by Handle, for which you seek the integer value, as follows:

Handle Field
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_GetIntegerProcType)

(VW_Handle,
VW_FieldNameType,
VW_Integer FAR *);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 339

 4 Application Programming Interface
VW_GetIsolatedRegion

VW_GetIsolatedRegion
ErrorCode = VW_GetIsolatedRegion (LogonHandle, IsolatedRegion)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

IsolatedRegion long

See “API Calling Sequence” on page 484 for context.

Result of Call This API uses LogonHandle to identify in IsolatedRegion the isolated
region in which you are working.

C typedef typedef VW_Error (VWAPIENTRY *VW_GetIsolatedRegionProcType)

(VW_LogonHandle,
VW__IsolatedRegionType FAR *);

See Also:
“VW_Logon” on page 373

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 340

 4 Application Programming Interface
VW_GetMachineId

VW_GetMachineId
ErrorCode = VW_GetMachineId (LogonHandle, MachineId)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

MachineId string

See “API Calling Sequence” on page 484 for context.

Result of Call This API uses LogonHandle to identify in MachineId the workstation to
which you are logged on and on which you are running the application.

C typedef typedef VW_Error (VWAPIENTRY *VW_GetMachineIdProcType)

(VW_LogonHandle,
VW__MachineIdNameType FAR);

See Also:
“VW_Logon” on page 373

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 341

 4 Application Programming Interface
VW_GetOperationName

VW_GetOperationName
ErrorCode = VW_GetOperationName (QueueElementHandle, Opera-
tionName)

Visual Basic
Object Browser
Input/Output Data Type Source
QueueElementHandle long VW_NextWorkObject
ToBrowse( )

OperationName string

See “API Calling Sequence” on page 484 or for context.

Result of Call This API returns in OperationName the name of the next Operation
that will process the Work Object identified by QueueElementHandle.
OperationName identifies the read-only name of this Operation and it
points to a writable location in memory.

Call this after calling VW_GetOperationNameSize( ), so you will know

the amount of space you must allocate for the name.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetOperationNameProcType)

(VW_Handle,
VW_OperationNameType FAR);

See Also:
“VW_GetOperationNameSize” on page 343

“VW_NextWorkObjectToBrowse” on page 388

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 342

 4 Application Programming Interface
VW_GetOperationNameSize

VW_GetOperationNameSize
ErrorCode = VW_GetOperationNameSize (QueueElementHandle,
Size)

Visual Basic
Object Browser
Input/Output Data Type Source
QueueElementHandle long VW_NextWorkObject
ToBrowse( )

Size long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Size the number of bytes in the name of the next
Operation that will process the Work Object identified by QueueEle-
mentHandle. Call it before calling VW_GetOperationName( ) to deter-
mine the amount of space you must allocate for the name.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetOperationNameSizeProcType)

(VW_Handle,
unsigned integer FAR *);

See Also:
“VW_GetOperationName” on page 342

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 343

 4 Application Programming Interface
VW_GetParameterMode

VW_GetParameterMode
ErrorCode = VW_GetParameterMode (Handle, ParameterName, Di-
rection)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

ParameterName string Developer

Direction long

See “API Calling Sequence” on page 484 for context.

Summary This API returns the direction in which data passes in an active Work
Performer Operation parameter or field: 0 is in,1 is out, and 2 is in and
out (inout).

Result of Call This API returns in Direction the direction of the active Work Per-
former Operation parameter you identify in ParameterName. The direc-
tion is one of the following:

0 in Data passes from Work Object to Operation

1 out Operation generates data and passes it to

Work Object

2 inout Work Object passes data to Operation, Op-

eration processes data and changes data

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 344

 4 Application Programming Interface
VW_GetParameterMode

value, Operation passes changed data value

back to Work Object (also known as inout
mode)

Handle identifies the Work Object for which the Operation is current, as
follows:

Handle Parameter is for this field

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

Tips Visual WorkFlo returns a runtime error if a Work Performer attempts to

read as input any data from a Work Object parameter that is in out
mode.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetParameterModeProcType)

(VW_Handle,
VW_ParameterNameType FAR,
VW_DirectionType FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 345

 4 Application Programming Interface
VW_GetQueueNames

VW_GetQueueNames
ErrorCode = VW_GetQueueNames (LogonHandle, QueueNames)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

QueueNames Variant
NumberOfElements Not applicable

See “API Calling Sequence” on page 484 for context.

Summary This API lists the names of Work Queues and System Queues in the
Online repository. For the C interface it also returns the number of
queues.

Result of Call This API lists in the array QueueNames the names of Work Queues
and System Queues in the Online repository. This API returns:

• Strings in the array QueueNames, each of which is the name of a

queue that is in the Online repository

• For OLE wrapper DLL interface, the number of strings in the array,
in NumberOfElements

Tips This API allocates memory for QueueNames (and returns the array
pointer to the caller), but you must free the array by calling VW_

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 346

 4 Application Programming Interface
VW_GetQueueNames

FreeArrayPtr( ) when you no longer need it. (Provide VW_STRING-

TYPE to VW_FreeArrayPtr( ) as its ArrayType input parameter.)

C typedef typedef VW_Error(VWAPIENTRY *VW_GetQueueNamesProcType)

(VW_LogonHandle,
VW_ArrayPtrType FAR *
long FAR *);

See Also:
“VW_GetWorkPerformerClassNames” on page 361 for comparison

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 347

 4 Application Programming Interface
VW_GetString

VW_GetString
ErrorCode = VW_GetString (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value string

See “API Calling Sequence” on page 484 for context.

Summary This API returns a parameter value that is of type string. Call it after
calling VW_GetStringSize( ), so you will know the amount of space you
must allocate for the string.

Result of Call This API returns in Value a parameter value that is of type string.
Specify in FieldName the field or parameter name in the object identi-
fied by Handle, for which you seek the string value, as follows:

Handle Value
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 348

 4 Application Programming Interface
VW_GetString

C typedef typedef VW_Error(VWAPIENTRY *VW_GetStringProcType)

(VW_Handle,
VW_FieldNameType,
VW_String);

See Also:
“VW_GetStringSize” on page 350

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 349

 4 Application Programming Interface
VW_GetStringSize

VW_GetStringSize
ErrorCode = VW_GetStringSize (Handle, FieldName, Size)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Size long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Size the number of bytes in a string of the object
identified by Handle.

Specify in FieldName the field or parameter name in the object identi-

fied by Handle, for which you seek the string size, as follows:

Handle Size of this field or parameter

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

Tips Call this before calling VW_GetString( ) to determine the amount of

space you must allocate for the string.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 350

 4 Application Programming Interface
VW_GetStringSize

C typedef typedef VW_Error(VWAPIENTRY *VW_GetStringSizeProcType)

(VW_Handle,
VW_FieldNameType,
unsigned int FAR *);

See Also:
“VW_GetString” on page 348

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 351

 4 Application Programming Interface
VW_GetTime

VW_GetTime
ErrorCode = VW_GetTime (Handle, FieldName, Value)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

FieldName string Developer

Value long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in Value a parameter or field value that is of type time.
It expresses the number of seconds that have passed since midnight,
January 1, 1970 Coordinated Universal Time (UTC, formerly Green-
wich Mean Time).

Specify in FieldName the name of the field or parameter in the object

identified by Handle, for which you seek the time value, as follows:

Handle Value
WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 352

 4 Application Programming Interface
VW_GetTime

Tips A time value is a 32-bit long and, as such, can specify a time that is no
earlier than August 16 21:26:41, 1906 and no later than January 13
12:53:20, 2038.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetTimeProcType)

(VW_Handle,
VW_FieldNameType,
VW_Time FAR *);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 353

 4 Application Programming Interface
VW_GetWobSignature

VW_GetWobSignature
ErrorCode = VW_GetWobSignature (Handle, WobSignature)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle, as one of the fol- long
lowing:

QueueElementHandle VW_NextWorkObjectTo
Browse( )

OperationHandle VW_LockWorkObject( )

WobAccessHandle VW_GetAccessHandle( )
or
VW_WobQueryGetAcces
Handle( )

WobSignature string

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in the string WobSignature the signature that
uniquely identifies a Work Object in the VWService. Handle identifies
the Work Object.

Tips The format of this signature may change in a subsequent release.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetWobSignatureProcType)

(VW_Handle,
VW_WobSignatureType FAR);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 354

 4 Application Programming Interface
VW_GetWorkClassNames

VW_GetWorkClassNames
ErrorCode = VW_GetWorkClassNames (LogonHandle, WorkClass-
Names, IncludeInternalClasses)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

IncludeInternalClasses integer Developer

WorkClassNames Variant VW_FreeArrayPtr( ) for OLE

wrapper DLL interface
NumberOfElements VW_FreeArrayPtr( )

See “API Calling Sequence” on page 484 for context.

Summary This API lists in an array the names and, for the C interface, the num-
ber of Work Classes in the Online repository. You can list and count all
class names or only the names of classes you defined.

Result of Call This API returns:

• Strings in the array WorkClassNames, each of which is the name

of a Work Class that is in the Online repository

• For the C interface, the number of strings in the array, in NumberOf

Elements

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 355

 4 Application Programming Interface
VW_GetWorkClassNames

Select which Work Class names to list and count with the following set-
ting:

IncludeInternalClasses = true
All Work Classes in the Online repository

IncludeInternalClasses = false
All user-defined Work Classes in the Online repository
(This excludes system Work Classes.)

Tips This API allocates memory for WorkClassNames, but you must free
the array by calling VW_FreeArrayPtr( ) when you no longer need it.
(Provide VW_STRINGTYPE to that API as the ArrayType input param-
eter.)

C typedef typedef VW_Error(VWAPIENTRY *VW_GetWorkClassNamesProcType)

(VW_LogonHandle,
VW_ArrayPtrType FAR*,
long FAR*,
VW_Boolean);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 356

 4 Application Programming Interface
VW_GetWorkObjectLockStatus

VW_GetWorkObjectLockStatus
ErrorCode = VW_GetWorkObjectLockStatus (Handle,
LockStatus, MachineId)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

LockStatus long

MachineId string

See “API Calling Sequence” on page 484 for context.

Result of Call This API indicates in LockStatus whether a Work Object is locked
and, if it is, identifies in MachineId the workstation on which it is
locked, as follows:

LockStatus Returned in MachineId

VW_WOB_NOT_LOCKED Null ("“) for the workstation identity
VW_WOB_USER_LOCKED Identity of the workstation on which a
user has locked the Work Object
VW_WOB_SYSTEM_LOCKED Identity of the workstation on which the
system has locked the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 357

 4 Application Programming Interface
VW_GetWorkObjectLockStatus

Handle identifies the Work Object, as follows:

Identifier of the Work Object

Handle for which you seek lock status
QueueElementHandle Work Queue field
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object

C typedef typedef VW_Error VWAPIENTRY *VW_GetWorkObjectLockStatusProcType)

(VW_Handle,
VW_LockStatusType FAR *,
VW__MachineIdNameType FAR);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 358

 4 Application Programming Interface
VW_GetWorkObjectName

VW_GetWorkObjectName
ErrorCode = VW_GetWorkObjectName (Handle, WorkObjectName)

Visual Basic
Object Browser
Input/Output Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

WorkObjectName string

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in WorkObjectName the name of the Work Object
identified by Handle, as follows:

Handle Identifying Field

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

The returned Work Object name is the human-readable-string equiva-

lent of the Work Object tag. (See “Work Object Identification” on
page 52 to compare the various forms of Work Object identity.)

C typedef typedef VW_Error (VWAPIENTRY *VW_GetWorkObjectNameProcType)

(VW_Handle,
VW_WorkObjectNameType FAR);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 359

 4 Application Programming Interface
VW_GetWorkObjectName

See Also:
Visual WorkFlo Technical Notes to compare the Work Object name
with the Work Object ID, the Work Object tag, and the Work Object
number

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 360

 4 Application Programming Interface
VW_GetWorkPerformerClassNames

VW_GetWorkPerformerClassNames
ErrorCode = VW_GetWorkPerformerClassNames (LogonHandle,
WorkPerformerClassNames, IncludeInternalClasses)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

WorkPerformerClass Variant VW_FreeArrayPtr( ) for OLE

Names wrapper DLL interface

IncludeInternalClasses integer Developer

NumberOfElements Not applicable VW_FreeArrayPtr( ) for OLE

wrapper DLL interface

See “API Calling Sequence” on page 484 for context.

Summary This API lists the names and, for the C interface, the number of Work
Performer Classes in the Online repository. You can list and count all
Work Performer Class names or only the names of classes you de-
fined.

Result of Call This API returns:

• Strings in the array WorkPerformerClassNames, each of which is

the name of a Work Performer Class that is in the Online repository

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 361

 4 Application Programming Interface
VW_GetWorkPerformerClassNames

• For the C developer, the number of strings in the array, in Number

OfElements

Select which Work Performer Class names to list and count with the
following setting:

IncludeInternalClasses = true
All Work Performer Classes in the Online repository

IncludeInternalClasses = false
All user-defined Work Performer Classes in the Online repository
(This excludes system classes.)

Tips If you set IncludeInternalClasses to true, this API returns the names of
Work Performer Classes, which is to say it returns the names of Work
Queues, with the exception of the WorkPerformerObject class (the
base Work Performer Class). Although that is a Work Performer Class,
there is no associated Work Queue.

To obtain a list of all queue names, including those of System Queues,

call VW_GetQueueNames( ).

This API allocates memory for WorkPerformerClassNames, but you

must free the array by calling VW_FreeArrayPtr( ) when you no longer
need it. (Provide VW_STRINGTYPE to that API as the ArrayType input
parameter.)

C typedef typedef VW_Error(VWAPIENTRY *VW_

GetWorkPerformerClassNamesProcType)
(VW_LogonHandle,
VW_ArrayPtrType FAR *,
long FAR *,
VW_Boolean);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 362

 4 Application Programming Interface
VW_GetWorkPerformerClassNames

See Also:
“VW_GetQueueNames” on page 346 to obtain a list of all queues, in-
cluding System Queues

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 363

 4 Application Programming Interface
VW_GetWorkPerformerHandle

VW_GetWorkPerformerHandle
ErrorCode = VW_GetWorkPerformerHandle (OperationHandle,
WorkPerformerHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
OperationHandle long VW_LockWorkObject( )

WorkPerformerHandle long VW_BeginBrowsingWork

Queue( )
or
VW_LeaveWork( )

VW_LogMessage( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in WorkPerformerHandle a handle to an active Work

Performer. OperationHandle identifies the Work Performer.

C typedef typedef VW_Error(VWAPIENTRY *VW_GetWorkPerformerHandleProcType)

(VW_OperationHandle,
VW_Handle FAR *);

See Also:
“VW_LockWorkObject” on page 367

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 364

 4 Application Programming Interface
VW_GetWorkQueueDepth

VW_GetWorkQueueDepth
ErrorCode = VW_GetWorkQueueDepth (LogonHandle, QueueName,
QueueDepth)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

QueueName string Developer

QueueDepth long

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in QueueDepth the number of Work Objects in the
queue you name in QueueName. The number includes all Work Ob-
jects in that queue—locked, unlocked, bound, and unbound Work Ob-
jects.

Note Visual WorkFlo enhancements have caused this API’s functionality to

outpace its name; it now indicates the depth of System Queues as well
as Work Queues.

C typedef typedef VW_Error (VWAPIENTRY *VW_GetWorkQueueDepthProcType)

(VW_LogonHandle,
VW_ClassNameType FAR,
long FAR *);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 365

 4 Application Programming Interface
VW_LeaveWork

VW_LeaveWork
ErrorCode = VW_LeaveWork (WorkPerformerHandle)

Visual Basic
Object Browser
Input Data Type Source
WorkPerformerHandle long VW_ReportToWork( )
VW_
GetWorkPerformerHandle( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API invalidates and frees the resources allocated to WorkPerform-
erHandle and any of these associated handles:

BrowseSessionHandle
QueueElementHandle
OperationHandle

Tips Call this API once for each queue browsed before shutdown of the
Work Performer.

C typedef typedef VW_Error(VWAPIENTRY *VW_LeaveWorkProcType)

(VW_ActiveWPHandle);

See Also:
“VW_GetWorkPerformerHandle” on page 364

“VW_ReportToWork” on page 421

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 366

 4 Application Programming Interface
VW_LockWorkObject

VW_LockWorkObject
ErrorCode = VW_LockWorkObject (QueueElementHandle, Operation-
Handle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QueueElementHandle long VW_
NextWorkObjectToBrowse( )

OperationHandle long Data accessa APIs:

VW_GetXXX( )
VW_SetXXX( )
VW_BindToUser( )
VW_Call( )
VW_CurrentException( )
VW_GetBindings( )
VW_GetWobSignature( )
VW_
GetWorkPerformerHandle( )
VW_RaiseException( )
VW_TerminateWorkObject( )
VW_UnBind( )
VW_UnlockAndDispatch( )
VW_UnlockWorkObject( )
a. APIs such as VW_GetInteger and VW_SetInteger

See “API Calling Sequence” on page 484 for context.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 367

 4 Application Programming Interface
VW_LockWorkObject

Summary This API locks a Work Object so that the caller can perform the current
Operation.

Result of Call This API locks the Work Object (in a Work Queue during a browse ses-
sion) identified by QueueElementHandle, so that the caller can perform
the current Operation. Visual WorkFlo cannot lock this Work Object
again until after a call to VW_UnlockAndDispatch( ) or VW_
UnlockWorkObject( ). The returned OperationHandle remains valid
until after a call to one of these:

VW_UnlockAndDispatch( )

VW_UnlockWorkObject( )

VW_LeaveWork( )

Tips Use Visual WorkFlo/Conductor, the VW_GetAccessHandle( ) API, or

the VW_WobQueryGetAccessHandle( ), rather than this API, to lock,
modify, and dispatch a Work Object in a System Queue.

Call VW_UnlockAndDispatch( ) or VW_UnlockWorkObject( ) when you

are finished with the Work Object’s processing.

C typedef typedef VW_Error(VWAPIENTRY *VW_LockWorkObjectProcType)

(VW_QueueElementHandle
VW_OperationHandle FAR *);

See Also:
“VW_BindToUser” on page 272

“VW_Call” on page 288

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 368

 4 Application Programming Interface
VW_LockWorkObject

“VW_CurrentException” on page 295

“VW_GetBindings” on page 314

“VW_GetInteger” on page 339 and “VW_SetInteger” on page 452 for

sample data access APIs

“VW_GetWobSignature” on page 354

“VW_GetWorkPerformerHandle” on page 364

“VW_RaiseException” on page 419

“VW_TerminateWorkObject” on page 458

“VW_UnBind” on page 460

“VW_UnlockAndDispatch” on page 461

“VW_UnlockWorkObject” on page 462

The Visual WorkFlo Installation and Administration Handbook , “VW_

GetAccessHandle” on page 304, and “VW_WobQueryGetAccessHan-
dle” on page 472 for more information on how to lock, modify, and dis-
patch in a System Queue

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 369

 4 Application Programming Interface
VW_LogMessage

VW_LogMessage
ErrorCode = VW_LogMessage (WorkPerformerHandle, UserDefined-
Message, LoggingOption)

Visual Basic
Object Browser
Input Data Type Source
WorkPerformerHandle long VW_ReportToWork( )

UserDefinedMessage string Developer

LoggingOption long Developer

See “API Calling Sequence” on page 484 for context.

Summary The calling Work Performer uses this API to log a user-defined mes-
sage for a specific event logging option.

The corresponding event logging option must be enabled in the Work

Performer Class and the Logging Master of the isolated region.

Result of Call The calling Work Performer (identified by WorkPerformerHandle) uses

this API to log the string UserDefinedMessage for the logging option
LoggingOption to the log table.

Message Length
The message may be up to the maximum number of bytes long speci-
fied in the SVCAPI.H file as VW_MAXMESSAGELEN. (This is 80
bytes.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 370

 4 Application Programming Interface
VW_LogMessage

Logging Option
The logging option must be on (it must be set = 1 with Composer) in
the Work Performer’s log vector and in the system log vector. Only the
following options are valid:

Log vector option set Visual WorkFlo

with Composer Logging option Release 2.0 equivalent
User-defined message 1 VW_User11Msg VW_WODebugOption
VW_User12Msg VW_WOMiscOption
VW_User13Msg VW_WOSystemOption
VW_User14Msg VW_USER1Option
User-defined message 2 VW_User21Msg VW_WPDebugOption
VW_User22Msg VW_WPMiscOption
VW_User23Msg VW_WPSystemOption
VW_User24Msg USER2Option

Tips Compare the event logging provided by this API with trace logging for
debugging.

C typedef typedef VW_Error(VWAPIENTRY *VW_LogMessageProcType)

(VW_Handle,
VW_MessageType FAR,
VW_LogOption);

See Also:
The Visual WorkFlo Installation and Administration Handbook for more
information about trace and event logging

“VW_ReportToWork” on page 421

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 371

 4 Application Programming Interface
VW_Logoff

VW_Logoff
ErrorCode = VW_Logoff (LogonHandle)

Visual Basic
Object Browser
Input Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

See “API Calling Sequence” on page 484 for context.

Result of Call This API invalidates LogonHandle. Call it once before Work Performer
shutdown.

Tips If you are going to call VW_DispatchWorkObject( ), do this before call-

ing VW_Logoff( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_LogoffProcType)

(VW_LogonHandle);

See Also:
“VW_Logon” on page 373

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 372

 4 Application Programming Interface
VW_Logon

VW_Logon
ErrorCode = VW_Logon (LogonHandle)

Visual Basic
Object Browser Destination
Output Data Type (partial list)
LogonHandle long VW_AttachToWorkQueue( )
VW_CreateWorkObject( )
VW_Logoff( )
VW_LogQueryBegin( )
VW_
QsCreateQuerySpecifier( )
VW_WobQueryCreate( )

See “API Calling Sequence” on page 484 for context.

Result of Call A call to this API makes an application a Visual WorkFlo application. It
returns the unique logon ID, LogonHandle to the caller for use in sub-
sequent API calls if the caller previously used FileNET Logon and re-
sponded with the right user name and password. Otherwise, it causes
Visual WorkFlo to prompt for these.

At the PC workstation it logs the user onto a VWService and provides

access to the isolated region defined in the VW.INI file.

Before you call this API, compare its results with those of calling the
VW_LogonEx( ) API.

Tips Call it once at client-side application startup.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 373

 4 Application Programming Interface
VW_Logon

Call VW_Logoff( ) to free the resources associated with LogonHandle.

Call VW_Logon( ) from an application of any of the three categories:

creative, administrative, or Work Performer.

Visual WorkFlo sets LogonHandle to zero if there is an error.

For a 32-bit application, Visual WorkFlo API calls are now provided by
an OLE server, VWAPISRV.EXE. The OLE server loads at the time of
the first API call (when the application calls VW_Logon( ). Visual Work-
Flo also loads at this time. This may cause the loading of the VW_
Logon( ) call to appear slightly slower than expected (due to simulta-
neous loading of Visual WorkFlo), but initial loading of the application
is faster, because Visual WorkFlo has already loaded.

The OLE server unloads upon a call to VW_Logoff( ). Should you call
VW_Logon( ), VW_Logoff( ), then VW_Logon( ) again, there would be
a delay with the second VW_Logon( ) call because the OLE server
would have unloaded with the VW_Logoff( ) call and must now reload.
We recommend that you call VW_Logon( ) once at startup of your ap-
plication and that you call VW_Logoff( ) once at shutdown.

C typedef typedef VW_Error(VWAPIENTRY *VW_LogonProcType)

(VW_LogonHandle FAR *);

Example

OLE with Visual Basic

See “OLE with Visual Basic” on page 269 for an example in conjunc-
tion with calls to VW_AttachToWorkQueue and VW_BeginBrowsing-
WorkQueue.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 374

 4 Application Programming Interface
VW_Logon

See Also:
The Visual WorkFlo Installation and Administration Handbook

“VW_Logoff” on page 372

“VW_LogonEx” on page 376

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 375

 4 Application Programming Interface
VW_LogonEx

VW_LogonEx
ErrorCode = VW_LogonEx (UserName, Password, VWServiceName,
IsolatedRegion, LogonHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
UserName string Developer

Password string Developer

VWServiceName string Developer

IsolatedRegion long Developer

LogonHandle long (partial list)

VW_AttachToWorkQueue( )
VW_CreateWorkObject( )
VW_Logoff( )
VW_LogQueryBegin( )
VW_
QsCreateQuerySpecifier( )
VW_WobQueryCreate( )

See “API Calling Sequence” on page 484 for context.

Summary A call to this API makes an application a Visual WorkFlo application. It

logs a user onto the FileNET domain and a VWService. The user
specifies the VWService and isolated region within the VWService.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 376

 4 Application Programming Interface
VW_LogonEx

Use this API, rather than VW_Logon( ), to run an active Work Per-
former on the server. Use it in client-side or server-side applications.

Result of Call This API returns the unique logon ID, LogonHandle to the caller for
use in subsequent API calls. It logs the user, whom you specify in
UserName and protect with the password in Password, onto the
VWService you name in VWServiceName and gives the user access
to the following:

• Isolated region you specify in IsolatedRegion

• VWService, domain, and organization that you name as the three

segments of VWServiceName

"<ServiceName>:<Domain>:<Organization>"

VWServiceName

This allows the user to run more than one application in more than one
VWService and/or in more than one isolated region.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 377

 4 Application Programming Interface
VW_LogonEx

The following results when you specify an empty string (““), the name
of a server that is down, or an invalid value in VWServiceName :

Input parameter Result

UserName or Password In a Windows environment, Visual WorkFlo
prompts for these in a dialog box when the appli-
cation runs.

VWServiceName For a client-side application (including an applica-

tion that runs on Windows NT), Visual WorkFlo
logs the user onto the VWService specified in the
VW.INI file.
For a server-side application on AIX or HP, Visual
WorkFlo logs the user onto the VWService speci-
fied in the vwclient.ini file.

IsolatedRegion For a client-side application (including an applica-

tion that runs on Windows NT), the user attaches
to the isolated region specified in the VW.INI file.
For a server-side application on AIX or HP, the
user attaches to the isolated region specified in
the vwclient.ini file.
Specifying NO_REGION results in the same.

Tips Call VW_Logoff( ) to free the resources associated with LogonHandle.

Call VW_LogonEx( ) from an application of any of the three categories:

creative, administrative, or Work Performer.

Visual WorkFlo sets LogonHandle to zero if there is an error. If you

cancel out of logging on, a message returns that you were unable to
log on.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 378

 4 Application Programming Interface
VW_LogonEx

The OLE server loads when the application calls VW_LogonEx( ). Vi-
sual WorkFlo also loads at this time. This may cause the loading of the
VW_LogonEx( ) call to appear slightly slower than expected (due to si-
multaneous loading of Visual WorkFlo), but initial loading of the appli-
cation is faster, because Visual WorkFlo has already loaded.

The OLE server unloads upon a call to VW_Logoff( ). Should you call
VW_LogonEx( ), VW_Logoff( ), then VW_LogonEx( ) again, there
would be a delay with the second VW_LogonEx( ) call because the
OLE server would have unloaded with the VW_Logoff( ) call and must
now reload. FileNET recommends that you call VW_LogonEx( ) once
at startup of your Work Performer and that you call VW_Logoff( ) once
at shutdown.

C typedef typedef VW_Error(VWAPIENTRY *VW_LogonExProcType)

(VW_UserNameType FAR,
VW_PasswordType FAR,
VW_VWServiceNameType FAR,
VW_IsolatedRegionType,
VW_LogonHandle FAR *);

Example

OLE with Visual Basic

See “OLE with Visual Basic” on page 269 for an example in conjunc-
tion with calls to VW_AttachToWorkQueue and VW_BeginBrowsing-
WorkQueue.

See “Explanation of Code” on page 57 for sample code that contains a

call to this API.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 379

 4 Application Programming Interface
VW_LogonEx

See Also:
“VW_Logoff” on page 372

“VW_Logon” on page 373 for comparison

Visual WorkFlo Installation and Administration Handbook

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 380

 4 Application Programming Interface
VW_LogQueryBegin

VW_LogQueryBegin
ErrorCode = VW_LogQueryBegin (LogonHandle, QuerySpecifierHan-
dle, LogQueryHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

QuerySpecifierHandle long VW_

QsCreateQuerySpecifier( )

LogQueryHandle long VW_LogQueryEnd( )

VW_LogQuery
NextRecords( )

See “API Calling Sequence” on page 484 for context.

Summary This API creates and initializes a query session on log records.

Result of Call This API returns the handle LogQueryHandle, with which the user
may begin a query session on records logged for the query object
specified by the handle, QuerySpecifierHandle, or on all records
logged (if the value of QuerySpecifierHandle is nil).

The query object specified by QuerySpecifierHandle contains a refer-

ence to the runtime object, ILogQuery, which maintains the current log
record pointer.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 381

 4 Application Programming Interface
VW_LogQueryBegin

The type of log query you make depends on the system-defined index
key you input to the QuerySpecifierIndexKey parameter in the previous
call to VW_QsCreateQuerySpecifier( ), as follows:

Developer input to QuerySpecifierIndexKey

Type of Log Query in previous call to VW_QsCreateQuerySpecifier( )
Over a period F_LogTime
By Work Object tag F_LogWobTag

Tips After the log query, call the API, VW_LogQueryEnd( ), to free the asso-
ciated resources.

C typedef typedef VW_Error(VWAPIENTRY *VW_LogQueryBeginProcType)

(VW_LogonHandle,
VW_QuerySpecHandle,
VW_LogQueryHandle FAR *);

See Also:
“VW_LogQueryNextRecords” on page 384

“VW_LogQueryEnd” on page 383

“VW_QsCreateQuerySpecifier” on page 403

“Using the Index Key” on page 406

“Sample Log Query” on page 135 for sample administrative application

code

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 382

 4 Application Programming Interface
VW_LogQueryEnd

VW_LogQueryEnd
ErrorCode = VW_LogQueryEnd (LogQueryHandle)

Visual Basic
Object Browser
Input Data Type Source
LogQueryHandle long VW_LogQueryBegin( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API frees the handle, LogQueryHandle, releasing the resources
that were allocated by calling the API, VW_LogQueryBegin( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_LogQueryEndProcType)

(VW_LogQueryHandle);

See Also:
“VW_LogQueryBegin” on page 381

“VW_LogQueryNextRecords” on page 384

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 383

 4 Application Programming Interface
VW_LogQueryNextRecords

VW_LogQueryNextRecords
ErrorCode = VW_LogQueryNextRecords (LogQueryHandle, Maxi-
mumRecordsToRead, LogRecords, Done)

Visual Basic
Object Browser
Input/Output Data Type Source
LogQueryHandle long VW_LogQueryBegin( )

MaximumRecordsToRead long Developer

NumberRead Not applicable

LogRecords Variant

Done integer

See “API Calling Sequence” on page 484 for context.

Summary This API returns records logged for the specified query object or all
records logged (if the log query handle specifies no query object).

Result of Call This API returns in LogRecords an array of pointers to comma-delim-

ited log record strings.

The records in the strings are those that Visual WorkFlo logged on the
query object identified by LogQueryHandle. If LogQueryHandle identi-
fies no object, all records return in LogRecords. The records in each

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 384

 4 Application Programming Interface
VW_LogQueryNextRecords

string are field values, each separated by a comma, that return in the
following parameter order:

Parameter Source field

Time stamp F_TimeStamp
Event number F_EventType
Sequence F_SeqNumber
User name F_UserId (converted to a string)
Permanent workspace F_PermWorkSpaceId
Temporary workspace F_TempWorkSpaceId
Work Object number F_WorkObjectNumber
Parent Work Object number F_ParentWorkObjNum
Work Class name F_WorkClassId (converted to a string)
Work Performer name F_WPClassId (converted to a string)
Instruction Sheet name F_InstSheetId (converted to a string)
Instruction name F_WPOperationId (converted to a string)
Authored Instruction ID F_AuthWorkOrderId
Machine ID F_MachineId
Duration F_Duration
Work Object tag F_WorkObjectTag
Text F_Text

A sample record string follows:

8/15/1998 13:45:33,140,,SysAdmin:marge:FileNET,,,
7cfde85a86161d189ad10005a3d201\5,,Autoclaim,Unattended,Claim-
Assessment, CreateVoucher,,4,Patricia,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 385

 4 Application Programming Interface
VW_LogQueryNextRecords

The sample log record, above, contains the following information:

Parameter Value from the sample source field

Time stamp 8/15/1998 13:45:33
Event number 140
Sequence
User name SysAdmin:marge:FileNET
Permanent workspace
Temporary workspace
Work Object number 7cfde85a86161d189ad10005a3d201\5
Parent Work Object number
Work Class name AutoClaim
Work Performer name Unattended
Instruction Sheet name ClaimAssessment
Instruction name CreateVoucher
Authored Instruction ID
Machine ID 4
Duration 4
Work Object tag Patricia
Text

Specify in MaximumRecordsToRead the maximum number of records

you wish to retrieve.

For an OLE wrapper DLL application, this API returns in NumberRead

the number of records it retrieved and, for both interfaces, Done indi-
cates whether Visual WorkFlo has retrieved all of the records available

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 386

 4 Application Programming Interface
VW_LogQueryNextRecords

on the query object (Done = true) or whether there are further records
to retrieve (Done = false).

C typedef typedef VW_Error(VWAPIENTRY *VW_LogQueryNextRecordsProcType)

(VW_LogQueryHandle,
long,
long FAR *,
VW_ArrayPtrType*,
VW_Boolean*);

See Also:
“VW_LogQueryBegin” on page 381

“VW_LogQueryEnd” on page 383

Appendix C of the Visual WorkFlo Installation and Administration

Handbook for information about workspace.

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 387

 4 Application Programming Interface
VW_NextWorkObjectToBrowse

VW_NextWorkObjectToBrowse
ErrorCode = VW_NextWorkObjectToBrowse (BrowseSessionHandle,
QueueElementHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
BrowseSessionHandle long VW_
BeginBrowsingWorkQueue( )

QueueElementHandle long VW_GetAccessHandle( )

VW_GetOperationName( )
VW_
GetOperationNameSize( )
VW_GetWobSignature( )
VW_LockWorkObject( )

See “API Calling Sequence” on page 484 for context.

Summary This API returns a handle to a Work Object in a browsed queue.

Result of Call This API returns the handle QueueElementHandle on a Work Object
in the queue the user is browsing. BrowseSessionHandle identifies the
queue.

Use QueueElementHandle in reference to the Work Object in subse-

quent calls to various APIs. It remains valid until a call to one of the fol-
lowing APIs:

VW_EndBrowsingWorkQueue( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 388

 4 Application Programming Interface
VW_NextWorkObjectToBrowse

VW_LeaveWork( )

VW_UnlockWorkObject( ) under certain circumstances (see “VW_

UnlockWorkObject” on page 462 for details)

C typedef typedef VW_Error(VWAPIENTRY *VW_NextWorkObjectToBrowseProcType)

(VW_BrowseHandle,
VW_QueueElementHandle FAR *);

Example

OLE with Visual Basic

See “OLE with Visual Basic” on page 269 for an example in conjunc-
tion with a call to VW_BeginBrowsingWorkQueue.

See Also:
“VW_BeginBrowsingWorkQueue” on page 267

“VW_GetAccessHandle” on page 304

“VW_GetOperationName” on page 342

“VW_GetOperationNameSize” on page 343

“VW_GetWobSignature” on page 354

“VW_LockWorkObject” on page 367

“VW_UnlockWorkObject” on page 462

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 389

 4 Application Programming Interface
VW_QQueryBegin

VW_QQueryBegin
ErrorCode = VW_QQueryBegin (QuerySpecifierHandle, QueueName,
QueueQueryOptions, BatchSize, QueueQueryHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QuerySpecifierHandle long VW_
QsCreateQuerySpecifier( )

QueueName string Developer

QueueQueryOptions long Developer

BatchSize long Developer

QueueQueryHandle long VW_QQueryNextWork

Object( )
or
VW_QQueryNextLocked
WorkObject( )
VW_QQueryEnd( )

See “API Calling Sequence” on page 484 for context.

Summary This API starts a query in a specific queue by returning a queue query
handle. The query reads the data of one or more Work Objects, ac-
cording to your parameter specifications.

It allows you the option of locking Work Objects in the same step that
you query them, thereby optimizing performance.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 390

 4 Application Programming Interface
VW_QQueryBegin

Result of Call This API starts a query in the queue you name in QueueName by re-
turning the queue query handle QueueQueryHandle. The query
reads the data of the Work Object(s), according to the following:

• Contents of the query specifier, QuerySpecifierHandle

A previous call to VW_QsCreateQuerySpecifier( ) returns this.

• Your specification of the QueueQueryOptions

• Your specification of a BatchSize number of Work Objects

A queue query follows the sequence of calls shown in the diagram be-
low.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 391

 4 Application Programming Interface
VW_QQueryBegin

Queue Query API Calling Sequence

“VW_QsCreateQuerySpecifier”

“VW_QQueryBegin”

VW_QQ_WANT_TO_LOCK No “VW_QQueryNextWorkObject”
specified in QueueQueryOptions?

Yes “VW_LockWorkObject”

“Get Data”

“VW_QQueryNextLockedWorkObject”

“Set Data” and “Get Data”

“VW_UnlockAndDispatch”

“VW_QQueryEnd”

BatchSize is the maximum number of Work Objects the data of which

Visual WorkFlo transfers in a single access of the server. (Visual Work-
Flo may transfer the data of fewer Work Objects than BatchSize at a
time if the query’s use of system resources is excessive.)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 392

 4 Application Programming Interface
VW_QQueryBegin

You may apply one or more of the following query options with Queue-
QueryOptions:

Option
Value in QueueQueryOptions code Result
VW_QQ_NO_OPTIONS 0x0 If specified:
All values are false

VW_QQ_READ_LOCKED 0x1 If specified:

Reads locked and unlocked Work
Objects

If not:
Reads only unlocked Work Objects

VW_QQ_READ_BOUND 0x2 If specified:

Reads bound and unbound Work
Objects

If not:
Reads only unbound Work Objects

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 393

 4 Application Programming Interface
VW_QQueryBegin

Option
Value in QueueQueryOptions code Result
VW_QQ_READ_UNWRITABLE 0 x 4 If specified:
Reads writable and unwritable Work
Objects

If not:
Reads only writable Work Objects

VW_QQ_WANT_TO_LOCK 0 x 8 If specified:
Locks the Work Objects to which
handles returned from the call to
VW_QsCreateQuerySpecifier( )
Use QueueQueryHandle in subse-
quent call to VW_
QQueryNextLockedWorkObject( ).

If not:
Use QueueQueryHandle in subse-
quent call to VW_
QQueryNextWorkObject( ).

Sample Suppose that:

Queue Query
• Your specifications (from the previous call to VW_QsCreateQue-
rySpecifier) make 40 Work Objects, in the queue you name in
QueueName, eligible for work.

• You have called VW_QQueryBegin( ) and have input a BatchSize

of 4.

Visual WorkFlo moves the data of four Work Objects from the specified
queue to your workstation memory. At this point, you call VW_QQue-
ryNextWork Object( ) and access the first of the four Work Objects in

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 394

 4 Application Programming Interface
VW_QQueryBegin

the batch, as shown in the preceding diagram and the following se-
quence.

Call VW_QsCreateQuerySpecifier( )
Call VW_QQueryBegin(4)
[Visual WorkFlo returns the handles of Work Objects 1-4 (of 40), mak-
ing their data available.]

Call:

VW_QQueryNextWorkObject( )
to return queue element handle 1 of 40

VW_QQueryNextWorkObject( )
to return queue element handle 2 of 40

VW_QQueryNextWorkObject( )
to return queue element handle 3 of 40

VW_QQueryNextWorkObject( )
to return queue element handle 4 of 40

VW_QQueryNextWorkObject( )
to return queue element handle 5 of 40
[Visual WorkFlo makes the data of another batch of 4 available without
your having to again call VW_QQueryBegin( ).]

When you call VW_QQueryNextWorkObject( ) a fifth time in the above

example, Visual WorkFlo knows that there are still 36 eligible Work Ob-
jects and it brings another batch of four Work Objects without your hav-

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 395

 4 Application Programming Interface
VW_QQueryBegin

ing to again call VW_QQueryBegin( ). (Compare this to Visual WorkFlo

returning an error message, as it would with VW_BeginBrowsingWork-
Queue( ) on the fifth call). You can continue to call VW_
QQueryNextWorkObject( ) in this way until you have queried all 40 eli-
gible Work Objects or until you decide to quit, by calling VW_QQuery-
End( ).

If you had specified VW_QQ_WANT_TO_LOCK in QueueQuery-

Options, Visual WorkFlo would have returned the queue query handles
and would have locked the Work Objects, as well. In this case you
could have called VW_QQueryNextLockedWorkObject( ) four times,
but you would access operation handles for only the first batch of four
Work Objects; Visual WorkFlo would not query the remaining 36. Call-
ing VW_QQueryBegin( ) with QueueQueryOptions set to VW_QQ_
WANT_TO_LOCK has an effect similar to that of calling the combina-
tion of VW_BeginBrowsingWorkQueue plus VW_LockWorkObject( ).

In both cases above, the system could retrieve fewer than BatchSize,
were system resource use high. However, the application would be
aware of this only if the Work Objects were locked upon query.

Tips This API allows you the option of locking Work Objects in the same
step that you query them, thereby optimizing system performance.

After the queue query, call the API, VW_QQueryEnd( ), to free the as-
sociated resources.

C typedef typedef VW_Error(VWAPIENTRY *VW_QQueryBeginProcType)

(VW_QuerySpecHandle,
VW_ClassNameType FAR,
QQOptionsType,
long,
VW_QueueQueryHandle FAR*);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 396

 4 Application Programming Interface
VW_QQueryBegin

See Also:
“VW_BeginBrowsingWorkQueue” on page 267 for comparison

“VW_QQueryEnd” on page 398

“VW_QQueryNextLockedWorkObject” on page 399

“VW_QQueryNextWorkObject” on page 401

“VW_QsCreateQuerySpecifier” on page 403

“VW_QsFreeQuerySpecifier” on page 414

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 397

 4 Application Programming Interface
VW_QQueryEnd

VW_QQueryEnd
ErrorCode = VW_QQueryEnd (QueueQueryHandle)

Visual Basic
Object Browser
Input Data Type Source
QueueQueryHandle long VW_QQueryBegin( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API frees the resources allocated by calling the VW_
QQueryBegin( ). If the previous call to VW_QQueryBegin( ) received
VW_QQ_WANT_TO_LOCK as input to its QueueQueryOptions (infor-
mation returned in QueueQueryHandle), this API unlocks the Work
Objects Visual WorkFlo locked for that call, provided they were not al-
ready unlocked or dispatched.

C typedef typedef VW_Error(VWAPIENTRY *VW_QQueryEndProcType)

(VW_QueueQueryHandle);

See Also:
“VW_QQueryBegin” on page 390

“VW_QQueryNextLockedWorkObject” on page 399

“VW_QQueryNextWorkObject” on page 401

“VW_QsCreateQuerySpecifier” on page 403

“VW_QsFreeQuerySpecifier” on page 414

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 398

 4 Application Programming Interface
VW_QQueryNextLockedWorkObject

VW_QQueryNextLockedWorkObject
ErrorCode = VW_QQueryNextLockedWorkObject (QueueQueryHan-
dle, OperationHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QueueQueryHandle long VW_QQueryBegin( )

OperationHandle long Data accessa APIs

VW_UnlockWorkObject( )
VW_UnlockAndDispatch( )
a. APIs such as VW_GetInteger and VW_SetInteger

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in OperationHandle the handle of the Operation that
will process the next Work Object, identified by QueueQueryHandle,
which returned in the batch queried by VW_QQueryBegin( ).

Call this API, rather than VW_QQueryNextWorkObject( ), if you locked

the Work Object by specifying VW_WANT_TO_LOCK in the Queue-
QueryOptions parameter of VW_QQueryBegin( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_

QQueryNextLockedWorkObjectProcType)
(VW_QueueQueryHandle,
VW_OperationHandle FAR*);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 399

 4 Application Programming Interface
VW_QQueryNextLockedWorkObject

See Also:
“VW_QQueryBegin” on page 390

“VW_QQueryEnd” on page 398

“VW_QQueryNextWorkObject” on page 401

“VW_QsCreateQuerySpecifier” on page 403

“VW_QsFreeQuerySpecifier” on page 414

“VW_UnlockAndDispatch” on page 461

“VW_UnlockWorkObject” on page 462

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 400

 4 Application Programming Interface
VW_QQueryNextWorkObject

VW_QQueryNextWorkObject
ErrorCode = VW_QQueryNextWorkObject (QueueQueryHandle,
QueueElementHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QueueQueryHandle long VW_QQueryBegin( )

QueueElementHandle long VW_LockWorkObject( )

Data accessa APIs

a. APIs such as VW_GetInteger and VW_GetFloat

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in QueueElementHandle the handle of the next Work
Object, identified by QueueQueryHandle, returned in the batch queried
by VW_QQueryBegin( ).

Call this API, rather than VW_QQueryNextLockedWorkObject( ), if you

did not specify VW_WANT_TO_LOCK in the QueueQueryOptions pa-
rameter of VW_QQueryBegin( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_QQueryNextWorkObjectProcType)

(VW_QueueQueryHandle
VW_QueueElementHandle FAR*);

See Also:
“VW_QQueryBegin” on page 390

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 401

 4 Application Programming Interface
VW_QQueryNextWorkObject

“VW_QQueryEnd” on page 398

“VW_QQueryNextWorkObject” on page 401

“VW_QsCreateQuerySpecifier” on page 403

“VW_QsFreeQuerySpecifier” on page 414

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 402

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

VW_QsCreateQuerySpecifier
ErrorCode = VW_QsCreateQuerySpecifier (LogonHandle,
QuerySpecifierHandle, QuerySpecifierIndexKey, QuerySpecifierMini-
mumValues, QuerySpecifierMinimumEqual, QuerySpecifierMaximum-
Values, QuerySpecifierMaximumEqual, QuerySpecifierFilter,
QuerySpecifierFilterSubstitutionVariables)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

QuerySpecifierHandle long VW_LogQueryBegin( )

VW_QQueryBegin( )
VW_QsFreeQuerySpecifier( )

QuerySpecifierIndexKey string Developer

QuerySpecifierMinimum- variant Developer

Values

QuerySpecifierMini- integer Developer

mumEqual

QuerySpecifierMaximum- variant Developer

Values

QuerySpecifierMaxi- integer Developer

mumEqual

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 403

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
QuerySpecifierFilter string Developer

QuerySpecifierFilterSubsti- variant Developer

tutionVariables

See “API Calling Sequence” on page 484 for context.

Summary This API returns a query specifier handle to use in retrieving, for exam-
ple:

• Data from the Work Objects in a queue

• Records from the log

The query specifier is a set of conditions Visual WorkFlo uses to select

records in a database.

Result of Call This API returns the query specifier handle QuerySpecifierHandle to
use in retrieving records.

Returning all Records

To obtain all data available in a queue or log, pass in a null string for
QuerySpecifierIndexKey and an empty array for QuerySpecifierMini-
mumValues and QuerySpecifierMaximumValues. When you do this,
Visual WorkFlo disregards QuerySpecifierMinimumEqual and Que-
rySpecifierMaximumEqual and returns data in default order according
specifications for the entity queried.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 404

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Returning Specific Data or Records

In subsequent queue and log query API calls, QuerySpecifierHandle
will limit a query to a range of database values in the index key you
name in QuerySpecifierIndexKey. The range is from the minimum
value defined by the heterogeneous array QuerySpecifierMinimumVal-
ues to the maximum value defined by the heterogeneous array Que-
rySpecifierMaximumValues.

Indicate by setting QuerySpecifierMinimumEqual and/or QuerySpecifi-

erMaximumEqual to ‘true’ that you wish to make the minimum and/or
maximum values inclusive, respectively. The setting ‘false’ causes the
subsequent query to exclude the record with the minimum and/or max-
imum value.

Filtering
If you wish to further limit the query, input a legal SQL “where” clause
subexpression to QuerySpecifierFilter.

Note Input of a subexpression, such as the following, to QuerySpecifierFilter

causes comparison against an empty string (two single quotes, in this
case) and no record in the database will satisfy the query:

FieldName > ‘’
FieldName = ‘’
FieldName < ‘’

Rather than input an empty string to QuerySpecifierMaximumValues

and QuerySpecifierMinimumValues, check for empty strings by input of
“FieldName is not null” or “FieldName is null” to QuerySpecifierFilter.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 405

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

The QuerySpecifierFilterSubstitutionVariables parameter enables you

to use only one statement as the QuerySpecifierFilter, but to taylor the
statement to your advantage. Specify in QuerySpecifierFilterSubstitu-
tionVariables the variables you wish to substitute for the QuerySpecifi-
erFilter items that begin with ":" or specify nil ("") if you wish to make
no substitution.

For example, you could filter out Work Objects that have a user-defined
queue field “priority” with a value of “low.”

Direct interface with the OLE server:

• Define the counterpart parameter of each restriction as an array,

which has the data type VARIANT (element vt = VT_ARRAY),
whether it contains one element or more.

• Input VT_EMPTY to QuerySpecifierMinimumValues, QuerySpecifi-

erMaximumValues, or QuerySpecifierFilter to omit any restriction
by these.

Use of the OLE wrapper DLL:

• Type is VW_VariantArray for QuerySpecifierMinimumValues,

QuerySpecifierMaximumValues, and QuerySpecifierFilter.

Using the Index Key

Provide in QuerySpecifierIndexKey the name of the index key in which
you are interested.

Queue Query
For queue query, the index key must include at least one user-defined
Work Queue field and it may include system-defined Work Queue
fields.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 406

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Note Visual WorkFlo automatically appends the F_UniqueId system-defined

Work Queue field to the index key.

User-defined. Input the index key the user defined in the Work Per-
former Class with the Composer program.

System-defined. Input a system-defined index key to be used in Work

Object data query. This contains one or more of the following Work
Queue fields:

F_WobNum
F_WorkSpaceId
F_Locked
F_LockMachine
F_LockUser
F_LockTime
F_BindPending
F_BoundUser
F_BoundMachine
F_Tag
F_OperationId
F_WorkClassId
F_EnqueueTime
F_CreateTime
F_InstrSheetId
F_WorkOrderId
F_SortOrder

The above list of system fields, on which an application can specify a

query, is a subset of the system fields the “VW_GetField” API can re-
turn.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 407

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

If you input a system-defined index key to find Work Object data, use
one of the following:

Fields in the index key

Index key (elements of the QuerySpecifierIndexKey array)
F_Fifo (F_UniqueId)
F_SortRule (F_Locked, F_SortOrder, F_UniqueId)
F_WobNum (F_WobNum)

The first element of each array above is required.

Log Query
If you input a system-defined index key to find a log record, use one of
the following:

Fields in the index key

Index key (elements of the QuerySpecifierIndexKey array)
F_LogTime (F_TimeStamp, F_SeqNumber)
F_LogWobTag (F_WorkObjectTag, F_TimeStamp, F_SeqNumber)

The first element of each array above is required.

Limiting the Query Range

QuerySpecifierMinimumValues and QuerySpecifierMaximumValues,
each a heterogeneous array of index components, have n elements
each, the nth element of which represents the nth field in the index key.

n in the arrays < number of field names

in QuerySpecfierIndexKey

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 408

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

If the number of elements, n, in the array is less than the number of in-
dex key fields, then its missing elements, by definition, represent those
fields at the end of the index key. Visual WorkFlo ignores such missing
fields when it limits the query.

Examples
Suppose a manager assigns each employee a list of customers. So,
each Work Object (for example, an auto insurance claim) for which the
manager’s department is responsible is associated with an employee
and a customer. Each Work Object, therefore, has an EmployeeName
field and a CustomerName field. The Visual WorkFlo user builds an in-
dex key for the Work Object, using Visual WorkFlo/Composer, that
contains the fields EmployeeName and CustomerName, then names
the index key “EmplCust.”

The developer specifies EmplCust in QuerySpecifierIndexKey to query

a queue that contains Work Object data fields that have the following
index keys:

Barbara, Smith and Jones

Fred, Acme Design
Fred, Performance Unlimited
Fred, Wilson and Sons
Jack, Communication Source
Jack, Holiday Consultants

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 409

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Case 1:

Parameter Developer enters this

QuerySpecifierMinimumValues Array with one element:
the string ‘Fred’

QuerySpecifierMinimumEqual true

QuerySpecifierMaximumValues Array with one element:

the string ‘Fred’

QuerySpecifierMaximumEqual true

QuerySpecifierHandle returns records for the following:

Fred, Acme Design

Fred, Performance Unlimited
Fred, Wilson and Sons

Case 2:

Parameter Developer enters this

QuerySpecifierMinimumValues Array with one element:
the string ‘Barbara’

QuerySpecifierMinimumEqual true

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 410

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Parameter Developer enters this

QuerySpecifierMaximumValues Array with one element:
the string ‘Jack’

QuerySpecifierMaximumEqual false

QuerySpecifierHandle returns records for the following:

Barbara, Smith and Jones

Fred, Acme Design
Fred, Performance Unlimited
Fred, Wilson and Sons

Case 3:

Parameter Developer enters this

QuerySpecifierMinimumValues Array with two elements: the strings
‘Fred’ and ‘Performance Unlimited’

QuerySpecifierMinimumEqual false

QuerySpecifierMaximumValues Array with two elements: the strings

‘Jack’ and ‘Holiday Consultants’

QuerySpecifierMaximumEqual false

QuerySpecifierHandle returns records for the following:

Fred, Wilson and Sons

Jack, Communication Source

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 411

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

Comparison with Browse Modifier Rules

The query specifier provides a considerable performance advantage
over browsing with pre-selection, selection, and sort rules, because
the query specifier filter conditions execute within the database engine,
whereas, selection rules execute outside the database engine and si-
multaneous use of pre-selection and sort rules can result in unaccept-
able performance. The index key provides the same functionality with
high performance.

Tips To maximize performance, use the QuerySpecifierIndexKey to select

the smallest possible set of records, rather than greatly reduce the
matched set with QuerySpecifierFilter. For example, avoid selecting
100 records with the index key, then reducing the number of records to
10 with the filter.

A subsequent query that uses the QuerySpecifierHandle, returned by

this API, always returns records in ascending index order.

The type of an array element must be the same as that of its index key
counterpart.

Specifying nothing in an index key field returns everything in that field.

After the query, call VW_QsFreeQuerySpecifier( ) to free the resources

associated with the query specifier handle.

C typedef typedef VW_Error(VWAPIENTRY *VW_QsCreateQuerySpecifierProcType)

(VW_LogonHandle,
VW_QuerySpecHandle FAR*,
char FAR*,
VW_VariantArray *,
VW_Boolean,
VW_VariantArray *,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 412

 4 Application Programming Interface
VW_QsCreateQuerySpecifier

VW_Boolean,
char FAR *,
VW_VariantArray *);

See Also:
“VW_LogQueryBegin” on page 381

“VW_QQueryBegin” on page 390

“VW_QsFreeQuerySpecifier” on page 414

Sample query specification in “Sample Roster Query” on page 130,

“Sample Log Query” on page 135, and “Sample Queue Query” on
page 139

“VW_GetField” on page 326 to compare the whole list of System

Queue fields with those you can use in an index key

Visual WorkFlo Technical Notes for details about system-defined Work

Queue fields

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 413

 4 Application Programming Interface
VW_QsFreeQuerySpecifier

VW_QsFreeQuerySpecifier
ErrorCode = VW_QsFreeQuerySpecifier (QuerySpecifierHandle)

Visual Basic
Object Browser
Input Data Type Source
QuerySpecifierHandle long VW_
QsCreateQuerySpecifier( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API frees the handle, QuerySpecifierHandle, releasing the re-
sources that were allocated by calling the API, VW_
QsCreateQuerySpecifier( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_QsFreeQuerySpecifierProcType)

(VW_QuerySpecHandle);

See Also:
“VW_QQueryBegin” on page 390

“VW_QQueryEnd” on page 398

“VW_QQueryNextLockedWorkObject” on page 399

“VW_QQueryNextWorkObject” on page 401

“VW_QsCreateQuerySpecifier” on page 403

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 414

 4 Application Programming Interface
VW_QueueGetStats

VW_QueueGetStats
ErrorCode = VW_QueueGetStats (LogonHandle, QueueClassName,
StartTime, EndTime, TimeUnit, QueueStatistics)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

QueueClassName string Developer

QueueStartTime long Developer

QueueEndTime long Developer

QueueTimeUnit long Developer

QueueStatistics Variant

See “API Calling Sequence” on page 484 for context.

Summary This API returns statistics on a queue of Work Objects.

Result of Call This API returns in the array, QueueStatistics, the statistics Visual
WorkFlo collected on the queue you name in QueueClassName during
the period you specify between QueueStartTime and QueueEndTime.

The period begins with the first sample Visual WorkFlo takes following
the actual time you specify in QueueStartTime. It ends with the first

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 415

 4 Application Programming Interface
VW_QueueGetStats

sample Visual WorkFlo takes following the actual time you specify in
QueueEndTime .

Specify in QueueTimeUnit the unit of time you want Visual WorkFlo to

use in reporting the statistics, as follows:

Specify this if your

application uses the OLE Specify this if your application
Unit of Time server directly. uses the OLE wrapper DLL.
Interval 0 VW_INTERVAL
Second 1 VW_SECONDS
Minute 2 VW_MINUTES
Hour 3 VW_HOURS
Day 4 VW_DAYS
Week 5 VW_WEEKS
Month 6 VW_MONTHS
Year 7 VW_YEARS

The array, QueueStatistics, is heterogeneous (its elements vary in

data type). It returns a two-part header and a trailer of elements in the
following order:

Header elements that are also input to this API:

QueueClassName
QueueStartTime
QueueEndTime

Header elements that are statistics common to Work Classes and

Work Performer Classes:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 416

 4 Application Programming Interface
VW_QueueGetStats

Server request time Time of request on the server

First sample time Time of first sample

Final sample time Time of final sample

Number of samples Number of samples taken between first

and final sample times

Number of units Number of units of time that lapsed between

first and final sample times

Trailer of queue statistics:

Intitial number of queued Work Objects

Number of queued Work Objects that remain
Average Work Object processing time (%)
Average throughput (%)
Average queue delay (%)
Number of dequeued Work Objects
Number of queued Work Objects
Number of aborted Work Objects
Service time (%)
Aborted time (%)
Number of processed Work Objects
Queued Work Object rate (%)
Dequeued Work Object rate (%)
Queue growth rate (%)
Average queue depth
Average number of processed Work Objects
Average number of locked Work Objects

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 417

 4 Application Programming Interface
VW_QueueGetStats

Current queue depth

Current number of locked Work Objects

C typedef typedef VW_Error(VWAPIENTRY *VW_QueueGetStatsProcType)

(VW_LogonHandle,
VW_ClassNameType FAR,
VW_Time,
VW_Time,
VW_TimeUnit,
VW_VariantArray FAR *);

See Also:
“VW_LogQueryBegin” on page 381 for comparison

“VW_RosterGetStats” on page 423 for comparison

The Visual WorkFlo Installation and Administration Handbook

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 418

 4 Application Programming Interface
VW_RaiseException

VW_RaiseException
ErrorCode = VW_RaiseException (OperationHandle, ExceptionName,
ExceptionDescription)

Visual Basic
Object Browser
Input Data Type Source
OperationHandle long VW_LockWorkObject( )

ExceptionName string Developer

ExceptionDescription string Developer

See “API Calling Sequence” on page 484 for context.

Summary This API causes an exception-handling Instruction Sheet to execute for

a Work Object.

Call this, rather than VW_Call( ), when you wish to reject the values in
a Work Object’s data fields, say, for error recovery and reporting.

Result of Call This API causes an exception-handling Instruction Sheet to execute for
the Work Object on which the Operation identified by OperationHandle
is current. Supply the name of the exception handling Instruction Sheet
in the string ExceptionName and the description of the exception in the
string ExceptionDescription .

VW_RaiseException( ) is like VW_Call( ) in that they both:

• Cause Visual WorkFlo to execute another Instruction Sheet to pro-

cess the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 419

 4 Application Programming Interface
VW_RaiseException

• Call the exception handling Instruction Sheet immediately, thereby

invalidating OperationHandle and unlocking the Work Object

However, Visual WorkFlo processing of these differs, as follows:

VW_RaiseException( ) VW_Call( )
Disregards changes made to the Saves changes made to the Work
Work Object data fields Object data fields
Disables all active timers Preserves timers (both active and in-
active)
Causes a Work Object that is in se- Leaves a Work Object that is in se-
quenced mode to exit that mode quenced mode in that mode
Logs an event in the log table if the Records nothing in the log table
logging vector option, Work Object
Exception is on

C typedef typedef VW_Error(VWAPIENTRY *VW_RaiseExceptionProcType)

(VW_Handle,
VW_ExceptionNameType FAR,
VW_MessageType FAR);

See Also:
“VW_Call” on page 288

“VW_CurrentException” on page 295 to compare exception naming

and description

“VW_SequencedWait” for information about sequenced mode

The Visual WorkFlo/Composer Handbook for information on exception

handling Instruction Sheets

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 420

 4 Application Programming Interface
VW_ReportToWork

VW_ReportToWork
ErrorCode = VW_ReportToWork (WorkQueueHandle, WorkPerformer-
Handle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WorkQueueHandle long VW_AttachToWorkQueue( )

WorkPerformerHandle long VW_BeginBrowsingWork

Queue( )
VW_LeaveWork( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API, along with a previous call to VW_AttachToWorkQueue( ), es-
tablishes a Visual WorkFlo application as a Work Performer.

This API uses WorkQueueHandle to identify a WorkQueue.

The handle it returns, WorkPerformerHandle, is valid until after a call

to VW_LeaveWork( ).

Tips Call this API once for each queue browsed after startup of the Work
Performer.

Call VW_LeaveWork( ), when work is complete, to free the resources

this API allocates.

C typedef typedef VW_Error(VWAPIENTRY *VW_ReportToWorkProcType)

(VW_QueueHandle,
VW_ActiveWPHandle FAR *);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 421

 4 Application Programming Interface
VW_ReportToWork

Example

OLE with Visual Basic

See “OLE with Visual Basic” on page 269 for an example in conjunc-
tion with a call to VW_BeginBrowsingWorkQueue.

See Also:
“VW_AttachToWorkQueue” on page 264

“VW_BeginBrowsingWorkQueue” on page 267

“VW_LeaveWork” on page 366

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 422

 4 Application Programming Interface
VW_RosterGetStats

VW_RosterGetStats
ErrorCode = VW_RosterGetStats (LogonHandle, RosterClassName,
RosterStartTime, RosterEndTime, RosterTimeUnit, RosterStatistics)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

RosterClassName string Developer

RosterStartTime long Developer

RosterEndTime long Developer

RosterTimeUnit long Developer

RosterStatistics

See “API Calling Sequence” on page 484 for context.

Summary This API returns statistics on a roster.

Result of Call This API returns in the array, RosterStatistics, the statistics Visual
WorkFlo collected on the roster you name in RosterClassName during
the period you specify between RosterStartTime and RosterEndTime.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 423

 4 Application Programming Interface
VW_RosterGetStats

The period begins with the first sample Visual WorkFlo takes following
the time you specify in RosterStartTime . It ends with the first sample
Visual WorkFlo takes following the time you specify in RosterEndTime .

Specify in RosterTimeUnit the unit of time you want Visual WorkFlo to

use in reporting the statistics, as follows:

Specify this if your

application uses the OLE Specify this if your application
Unit of Time server directly. uses the OLE wrapper DLL.
Interval 0 VW_INTERVAL
Second 1 VW_SECONDS
Minute 2 VW_MINUTES
Hour 3 VW_HOURS
Day 4 VW_DAYS
Week 5 VW_WEEKS
Month 6 VW_MONTHS
Year 7 VW_YEARS

The array, RosterStatistics, is heterogeneous (its elements vary in

data type). It returns a two-part header and a trailer of elements in the
following order:

Header elements that are also input to this API:

RosterClassName
RosterStartTime
RosterEndTime

Header elements that are statistics common to Work Classes and

Work Performer Classes:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 424

 4 Application Programming Interface
VW_RosterGetStats

Server request time Time of request on the server

First sample time Time of first sample

Final sample time Time of final sample

Number of samples Number of samples taken between first

and final sample times

Number of units Number of units of time that lapsed between

first and final sample times

Trailer of roster statistics:

Intitial number of Work Objects

Initial number of parent Work Objects
Initial number of child Work Objects

Remaining number of Work Objects

Remaining number of parent Work Objects
Remaining number of child Work Objects

Number of created Work Objects

Number of created parent Work Objects
Number of created child Work Objects

Number of terminated Work Objects

Number of terminated parent Work Objects
Number of terminated child Work Objects

Creation rate (%)

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 425

 4 Application Programming Interface
VW_RosterGetStats

Parent creation rate (%)

Child creation rate (%)

Termination rate (%)

Parent termination rate (%)
Child termination rate (%)

Growth rate (%)

Parent growth rate (%)
Child growth rate (%)

Average number of active Work Objects

Average number of active parent Work Objects
Average number of active child Work Objects
(Note that periods of inactivity affect these averages.)

Average life span of Work Objects (%)

Average life span of parent Work Objects (%)
Average life span of child Work Objects (%)

Current number of active Work Objects

Current number of active parent Work Objects
Current number of active child Work Objects

C typedef typedef VW_Error(VWAPIENTRY *VW_RosterGetStatsProcType)

(VW_LogonHandle,
VW_ClassNameType FAR,
VW_Time,
VW_Time,
VW_TimeUnit,
VW_VariantArray FAR *);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 426

 4 Application Programming Interface
VW_RosterGetStats

See Also:
“VW_LogQueryBegin” on page 381 for comparison

“VW_QueueGetStats” on page 415 for comparison

The Visual WorkFlo Installation and Administration Handbook

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 427

 4 Application Programming Interface
VW_SequencedWait

VW_SequencedWait
ErrorCode = VW_SequencedWait (LogonHandle, Timeout, Done)

Visual Basic
Object Browser
Input/Output Data Type Source
LogonHandle long VW_LogonEx( )
or
VW_Logon

Timeout long Developer

Done integer

See “API Calling Sequence” on page 484 for context.

Summary This API reports whether there are any sequenced mode Work Object
data in client workstation memory.

If there is none, it reports this immediately. If there is such data in local

memory, it waits until there is none then returns the report that there
are none. If it has not reported by the end of a period you specify, it re-
ports at the end of that period that the data of Work Objects in se-
quenced mode remain in local memory.

Use this API to control the number of sequenced mode Work Object
data in workstation memory and to minimize transaction between the
workstation and server.

Result of Call This API reports in the boolean Done whether there is any sequenced
mode Work Object data in the caller’s workstation memory.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 428

 4 Application Programming Interface
VW_SequencedWait

If there is none, it reports Done = true, immediately. If there is such

data in local memory, it waits until there is none then returns Done =
true at that time. If it has not reported when the number of milliseconds
you specify in Timeout lapse, it reports at the end of that period that
the data of sequenced mode Work Objects remains in local memory,
with Done = false.

API Role in Sequenced Mode

VW_SequencedWait( ) is one of the APIs associated with sequenced
mode, a feature that enables the developer to control the sequence of
Operations from a workstation by instructing Visual WorkFlo to return
to local memory that Work Object data which another Operation will
process.

In Box Example
Suppose that you have a queue of Work Objects (a Work Queue) on a
server that are waiting to be processed—an “in box” queue. You could
run a Work Performer (call it InBox) from your workstation that would
browse the In Box queue for eligible Work Objects, then prompt the
user to select from among them. After the InBox Work Performer dis-
patched the user-selected Work Object, Visual WorkFlo would move
the Work Object’s data to the user’s workstation (local) memory, at
which point, the Work Object could be placed into sequenced mode.

The Instruction Sheet for our InBox application would look similar to
this:

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 429

 4 Application Programming Interface
VW_SequencedWait

Operation InBox

Begin Sequenced Mode

Operation A on Work Queue A

Operation B on Work Queue B

End Sequenced Mode

An expanded view of this Instruction Sheet, on the following page,

shows the type and tasks of each instruction.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 430

 4 Application Programming Interface
VW_SequencedWait

Operation InBox

- Browses InBox queue for Work Objects

- Prompts user to select a Work Object

- Unlocks/dispatches selected Work Object

- Waits, then checks to see whether any

of the Work Object data is still in
local memory

- Waits again or loops to browse InBox queue

for more Work Objects

Begin Sequenced Mode

(System Instruction)
Places the Work Object in sequenced mode

Operation A on Work Queue A

(by Work Performer A)
- Fetches the Work Object’s data
from local memory

- Unlocks/dispatches the Work Object

To Operation B

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 431

 4 Application Programming Interface
VW_SequencedWait

From Operation A

Operation B on Work Queue B

(by Work Performer B)
- Fetches the Work Object’s data
from local memory

- Unlocks/dispatches the Work Object

End Sequenced Mode

(System Instruction)
Ends sequenced mode on the Work Object

According to this Instruction Sheet, the workstation and server would

interact as shown in the diagram on the following page. In the diagram,
we see the use of APIs in sequenced mode.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 432

 4 Application Programming Interface
VW_SequencedWait

InBox Master
Work Performer Work Performer A Work Performer B

VW_BeginBrowsing VW_SequencedWob VW_SequencedWob

WorkQueue( ) Fetch( ) Fetch( )
VW_UnlockAnd VW_UnlockAnd VW_UnlockAnd
Dispatch( ) Dispatch( ) Dispatch( )
VW_Sequenced
Wait( )
4 8

Work Work
1 LOCAL Object 5 Object 9
MEMORY data data

WORKSTATION

3 7
SERVER

In Box Queue A Queue B

Queue
2 6 10

Sequenced Mode
Begin End

The developer uses the Work Performer ‘InBox’ as a control process

for subsequent Work Performers, ‘A’ and ‘B’ that work on a Work Ob-
ject in sequenced mode.

A description of the process in the diagram begins on the following

page.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 433

 4 Application Programming Interface
VW_SequencedWait

InBox
Master Work Performer

• Calls VW_BeginBrowsingWorkQueue( ) and VW_

NextWorkObjectToBrowse( ) to find Work Objects in Work Queues
or System Queues that are eligible for work (1)

• Prompts the user to select one of these Work Objects

• Calls VW_UnlockAndDispatch( ) (2)

• Calls VW_SequencedWait( ) to check whether there is any Work

Object data left in workstation local memory after a specified pe-
riod

The timeout period for this call is independent of the timeout peri-
ods for calls by Work Performers A and B.

• Repeats this instruction after user has waited for enough Work Ob-
ject data to clear local memory

System Instruction
BeginSequencedMode

Places the Work Object into sequenced mode

Visual WorkFlo moves the data of the selected Work Object from the
server into the user’s workstation local memory and locks it there. (3)

Please see the Visual WorkFlo/Composer Handbook for more informa-

tion on this System Instruction.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 434

 4 Application Programming Interface
VW_SequencedWait

Work Performer A

• Calls VW_SequencedWobFetch( ) to access a locked, sequenced-

mode Work Object’s data, in the workstation’s memory (4)

When Visual WorkFlo dispatches a Work Object to the next Work

Queue, if the system is in sequenced mode, the Work Object en-
ters the Work Queue locked by the workstation from which it was
dispatched. Then, only a Work Performer from this workstation
may fetch its data and the Work Performer must do so by calling
VW_SequencedWobFetch( ). See “VW_SequencedWobFetch” on
page 437.

Note that Work Performer A appears to unlock the Work Object

(with VW_UnlockAndDispatch) before the Queue B Work Per-
former operates on its data. However, the Work Object stays locked
to the workstation because it is in sequenced mode.

• Calls VW_UnlockAndDispatch( ) (5 and 6)

Work Performer B

• Calls VW_SequencedWobFetch( ) to access a locked Work Object

in sequenced mode (7 and 8)

• Calls VW_UnlockAndDispatch( ) (9)

System Instruction, EndSequencedMode

Causes the Work Object to exit sequenced mode (10)

After this instruction, Visual WorkFlo inserts the Work Object into the
normal, unlocked state and VW_SequencedWobFetch( ) may no
longer fetch its data.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 435

 4 Application Programming Interface
VW_SequencedWait

Please see the Visual WorkFlo/Composer Handbook for more informa-

tion on this System Instruction.

Tips Use sequenced mode when you wish to:

• Treat more than one Instruction as a single task, without interrupt-

ing Work Object processing until it is complete or until you (rather
than the system) decide to switch to another task

• Sequentially process multiple Operations on the selected Work Ob-

ject’s data, using several Work Performers at the workstation to
which the Work Object has been locked, thereby minimizing trans-
action between workstation and server

If you call VW_BindToUser( ) on a Work Object that is in sequenced

mode, Visual WorkFlo removes the Work Object from sequenced
mode and sends it to the Malfunction Instruction Sheet.

C typedef typedef VW_Error(VWAPIENTRY *VW_SequencedWaitProcType)

(VW_LogonHandle,
long,
VW_Boolean FAR *);

See Also:
“VW_SequencedWobFetch” on page 437

“VW_UnlockAndDispatch” on page 461

The Visual WorkFlo/Composer Handbook for more information on the

System Instructions, BeginSequencedMode and EndSequencedMode

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 436

 4 Application Programming Interface
VW_SequencedWobFetch

VW_SequencedWobFetch
ErrorCode = VW_SequencedWobFetch (WorkPerformerHandle, Time-
out, OperationHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WorkPerformerHandle long VW_ReportToWork( )

Timeout long Developer

OperationHandle long Data accessa APIs:

VW_UnlockWorkObject( )
VW_UnlockAndDispatch( )
a. APIs such as VW_GetInteger and VW_SetInteger

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns OperationHandle, the handle to the current Opera-
tion of the Work Performer identified by WorkPerformer on a locked
Work Object in sequenced mode, if any of the Work Object’s data ap-
pears in local workstation memory before the number of milliseconds
you specify in Timeout lapses.

It returns nil in OperationHandle if no sequenced mode Work Object

data appears in the local memory before Timeout expires.

This is the only way to obtain the Operation handle when a Work Ob-
ject is in sequenced mode.

It has the advantage over browsing that it accesses only local memory.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 437

 4 Application Programming Interface
VW_SequencedWobFetch

C Typedef typedef VW_Error(VWAPIENTRY *VW_SequencedWobFetchProcType)

(VW_ActiveWPHandle,
long,
VW_OperationHandle FAR *);

See Also:
“VW_LockWorkObject” on page 367 for comparison

“VW_NextWorkObjectToBrowse” on page 388 for comparison

“VW_SequencedWait” on page 428

“VW_UnlockAndDispatch” on page 461

The Visual WorkFlo/Composer Handbook for more information on the

System Instructions, BeginSequencedMode and EndSequencedMode

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 438

 4 Application Programming Interface
VW_SetArray

VW_SetArray
ErrorCode = VW_SetArray (Handle, FieldName, Array[ ], DataType)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Array[] string Developer

DataType long Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Summary This API sets an array of values into a specified field (for the OLE Auto-
mation interface).

Result of Call This API sets the values you specify in Array[] into the field you name
in FieldName. The field is in the object identified by Handle, as shown
in the following table:

Handle Values set into this field or parameter

WorkPerformerHandle Active Work Performer data field
OperationHandle Parameter of the Operation process-
ing the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 439

 4 Application Programming Interface
VW_SetArray

Handle Values set into this field or parameter

NewWorkObjectHandle Data field of a new Work Object
WobAccessHandle Work Object data field

Also, provide the following:

• In Array[]

Location of the memory you have allocated for the array, which you
obtained by calling VW_GetArray( )

• In DataType

Type of the data in the array

C typedef Not applicable

See Also:
“VW_GetArray” on page 307

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 440

 4 Application Programming Interface
VW_SetArrayPtr

VW_SetArrayPtr

Summary This API sets an array of values into a specified field (for applications
that use the OLE wrapper DLL).

Visual Basic
Object Browser
Input Data Type Source

Handlea Not applicable See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName Developer

ArrayPtr Developer

NumberOfElements Developer
DataType Developer
a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the values you specify in ArrayPointer into the field you
name in FieldName. The field is in the object identified by Handle, as
shown in the following table:

Handle Values set into this field or parameter

WorkPerformerHandle Active Work Performer data field
OperationHandle Parameter of the Operation process-
ing the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 441

 4 Application Programming Interface
VW_SetArrayPtr

Handle Values set into this field or parameter

NewWorkObjectHandle Data field of a new Work Object
WobAccessHandle Work Object data field

Also, provide the following:

• In ArrayPointer

Location of the memory you have allocated for the array or a

pointer to the array, which you obtained by calling VW_GetArray-
Ptr( )

Remember to free the array pointer by calling “VW_FreeArrayPtr” .

• In NumberOfElements

Number of elements in the array

These may be fewer than the elements in the Visual WorkFlo array.

• In DataType

Type of the data in the array

Tips Call VW_FreeArrayPtr( ) to free the array pointer.

C typedef typedef VW_Error(VWAPIENTRY *VW_SetArrayPtrProcType)

(VW_Handle,
VW_FieldNameType
VW_ArrayPtrType,
long,
VW_DataType);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 442

 4 Application Programming Interface
VW_SetArrayPtr

See Also:
“VW_FreeArrayPtr” on page 303

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 443

 4 Application Programming Interface
VW_SetBoolean

VW_SetBoolean
ErrorCode = VW_SetBoolean (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value integer Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the boolean value you specify in Value into the field you
name in FieldName. This field is in the object identified by Handle, as
follows:

Handle Value set in this field

WorkPerformerHandle Active Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object
NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 444

 4 Application Programming Interface
VW_SetBoolean

C typedef typedef VW_Error(VWAPIENTRY *VW_SetBooleanProcType)

(VW_Handle,
VW_FieldNameType,
VW_Boolean);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 445

 4 Application Programming Interface
VW_SetField

VW_SetField
ErrorCode = VW_SetField (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value string Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the value you specify in Value into the field you name in
FieldName. The field belongs to the object identified by Handle, as fol-
lows:

Handle Value set

WorkPerformerHandle Active Work Performer data field name
QueueElementHandle Work Queue field name
OperationHandle Parameter of the Operation process-
ing the Work Object
NewWorkObjectHandle Name of a data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 446

 4 Application Programming Interface
VW_SetField

Tips Specify Value as follows:

• Place single quotes around a string or an expression of

time (‘abcde’).

• Place single quotes around the elements of a string or time

array {‘a’,’b’,’c’}.

• Use all lower case for Boolean values: true or false.

C typedef typedef VW_Error (VWAPIENTRY *VW_SetFieldProcType)

(VW_Handle,
VW_FieldNameType,
VW_String);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 447

 4 Application Programming Interface
VW_SetFloat

VW_SetFloat
ErrorCode = VW_SetFloat (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value double Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the double value you specify in Value into the field you
name in FieldName. This field is in the object identified by Handle, as
follows:

Handle Value set in this field

WorkPerformerHandle Active Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object
NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 448

 4 Application Programming Interface
VW_SetFloat

C typedef typedef VW_Error(VWAPIENTRY *VW_SetFloatProcType)

(VW_Handle,
VW_FieldNameType,
VW_Float);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 449

 4 Application Programming Interface
VW_SetFPNumber

VW_SetFPNumber
ErrorCode = VW_SetFPNumber (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value Developer
a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Summary This API sets a value of type 16-byte decimal floating point into a field.
A call to it requires the WorkFlo Application Libraries.

Result of Call This API sets the floating-point decimal you specify in Value into the
field you name in FieldName. This field is in the object identified by
Handle, as follows:

Handle Value set in this field

WorkPerformerHandle Active Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 450

 4 Application Programming Interface
VW_SetFPNumber

Handle Value set in this field

NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_SetFPNumberProcType)

(VW_Handle,
VW_FieldNameType,
VW_FPNumber);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 451

 4 Application Programming Interface
VW_SetInteger

VW_SetInteger
ErrorCode = VW_SetInteger (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value long Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the integer you specify in Value into the field you name in
FieldName. This field is in the object identified by Handle, as follows:

Handle Value set in this field

WorkPerformerHandle Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object
NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_SetIntegerProcType)

(VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 452

 4 Application Programming Interface
VW_SetInteger

VW_FieldNameType,
VW_Integer);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 453

 4 Application Programming Interface
VW_SetString

VW_SetString
ErrorCode = VW_SetString (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value string Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Result of Call This API sets the string you specify in Value into the field you name in
FieldName. This field is in the object identified by Handle, as follows:

Handle Value set in this field

WorkPerformerHandle Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object
NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

C typedef typedef VW_Error(VWAPIENTRY *VW_SetStringProcType)

(VW_Handle,

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 454

 4 Application Programming Interface
VW_SetString

VW_FieldNameType,
VW_String);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 455

 4 Application Programming Interface
VW_SetTime

VW_SetTime
ErrorCode = VW_SetTime (Handle, FieldName, Value)

Visual Basic
Object Browser
Input Data Type Source

Handlea long See “Handle” on page 50 for

the various sources and types
of Handle.

FieldName string Developer

Value long Developer

a. Handle must be other than QueueElementHandle; this API cannot
set values into the data field of an unlocked Work Object.

See “API Calling Sequence” on page 484 for context.

Summary This API sets a value of type time into a field. Express the time in sec-
onds since midnight January 1, 1970 Coordinated Universal
Time (UTC).

Result of Call This API sets the number of seconds you specify in Value into the field
you name in FieldName. This field is in the object identified by Handle,
as follows:

Handle Value set in this field

WorkPerformerHandle Active Work Performer data field name
OperationHandle Parameter of the Operation process-
ing the Work Object

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 456

 4 Application Programming Interface
VW_SetTime

Handle Value set in this field

NewWorkObjectHandle Name of data field in a new Work Ob-
ject
WobAccessHandle Work Object data field name

Tips A time value is a 32-bit long and, as such, can specify a time that is no
earlier than August 16 21:26:41, 1906 and no later than January 13
12:53:20, 2038.

C typedef typedef VW_Error(VWAPIENTRY *VW_SetTimeProcType)

(VW_Handle,
VW_FieldNameType,
VW_Time);

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 457

 4 Application Programming Interface
VW_TerminateWorkObject

VW_TerminateWorkObject
ErrorCode = VW_TerminateWorkObject (Handle)

Visual Basic
Object Browser
Input Data Type Source
Handle long See “Handle” on page 50 for
the various sources and types
of Handle.

See “API Calling Sequence” on page 484 for context.

Result of Call This API terminates the Work Object identified by Handle, as follows:

Handle Identifying Field

OperationHandle Parameter of the Operation process-
ing the Work Object
WobAccessHandle Work Object data field name

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 458

 4 Application Programming Interface
VW_TerminateWorkObject

The result of the call depends on the event, as follows:

Event Result
Work Object termination The Terminate Instruction Sheet exe-
cutes, then Visual WorkFlo removes the
Work Object from the Online repository.
A second termination of the Work Visual WorkFlo immediately removes
Object before completion of the Ter- the Work Object from the Online reposi-
minate Instruction Sheet tory (without waiting for completion of the
Terminate Instruction Sheet.
WobAccessHandle or Operation- Visual WorkFlo reroutes the Work Object
Handle identifies a Work Object un- immediately and invalidates Handle.
der a active Work Performer
Operation

C typedef typedef VW_Error(VWAPIENTRY *VW_TerminateWorkObjectProcType)

(VW_Handle);

See Also:
“VW_LockWorkObject” on page 367

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 459

 4 Application Programming Interface
VW_UnBind

VW_UnBind
ErrorCode = VW_UnBind (Handle)

Visual Basic
Object Browser
Input Data Type Source
Handle, as one of these: long
OperationHandle VW_BindToUser( )
or
VW_LockWorkObject( )

WobAccessHandle
VW_WobQueryGetAccess-
Handle
or
VW_GetAccessHandle

See “API Calling Sequence” on page 484 for context.

Result of Call This API ends the binding restriction placed on processing of the Work
Object identified by Handle.

C typedef typedef VW_Error(VWAPIENTRY *VW_UnBindProcType)

(VW_Handle);

See Also:
“VW_BindToUser” on page 272

“VW_GetBindings” on page 314

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 460

 4 Application Programming Interface
VW_UnlockAndDispatch

VW_UnlockAndDispatch
ErrorCode = VW_UnlockAndDispatch (OperationHandle)

Visual Basic
Object Browser
Input Data Type Source
OperationHandle long VW_LockWorkObject( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API unlocks the Work Object identified by OperationHandle, up-
dates it with any Operation parameters that have returned from data
access1 APIs, and dispatches it to the next Work Queue. It invalidates
OperationHandle.

Tips Call VW_UnlockAndDispatch( ) when you finish processing a Work

Object that was locked by a call to VW_LockWorkObject( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_UnlockAndDispatchProcType)

(VW_Handle);

See Also:
“VW_LockWorkObject” on page 367

Return to “Locator” on page 242

1.Data access APIs, such as VW_GetInteger( ) and VW_SetInteger( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 461

 4 Application Programming Interface
VW_UnlockWorkObject

VW_UnlockWorkObject
ErrorCode = VW_UnlockWorkObject (OperationHandle)

Visual Basic
Object Browser
Input Data Type Source
OperationHandle long VW_LockWorkObject( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API unlocks the Work Object identified by OperationHandle, dis-
cards any operation parameters that have returned from data access1
APIs, and leaves it in the Work Queue, unchanged since a call to VW_
LockWorkObject( ) locked it. It invalidates OperationHandle.

Tips Call VW_UnlockWorkObject( ) when you finish processing a Work Ob-

ject that was locked by a call to VW_LockWorkObject( ).

C typedef typedef VW_Error(VWAPIENTRY *VW_UnlockWorkObjectProcType)

(VW_OperationHandle);

See Also:
“VW_LockWorkObject” on page 367

Return to “Locator” on page 242

1.Data access APIs, such as VW_GetInteger( ) and VW_SetInteger( )

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 462

 4 Application Programming Interface
VW_WobQueryCreate

VW_WobQueryCreate
ErrorCode = VW_WobQueryCreate (LogonHandle, WorkClassName,
WobQueryHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
LogonHandle long VW_LogonEx( )
or
VW_Logon

WorkClassName string Developer

WobQueryHandle long VW_SetString( )

VW_WobQueryEnd( )
VW_WobQueryExecute( )

See the example in “Administrative Application Development” on

page 64 and “API Calling Sequence” on page 484 for context.

Summary This API creates a query handle to access either of the following:

• Work Objects that are in a specific Work Class

• Work Objects that are in a specific Work Class and have a specific
Work Object ID value or Work Object number

Note If you specify Work Object number, you need not know which queue
the Work Object is in.

The Work Objects may be in either a Work Queue or a System Queue.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 463

 4 Application Programming Interface
VW_WobQueryCreate

Result of Call This API returns the query handle WobQueryHandle, to use with the
following Work Object query.

1 Call this API, VW_WobQueryCreate( ), specifying the name of the

Work Class in WorkClassName.

To access all Work Objects in the Work Class, skip to step 3.

To access Work Objects in the Work Class that have a specific ID or

number, call VW_SetString( ).

2 VW_SetString( ) receives the following input:

• WobQueryHandle (into Handle)

Output of the step 1 call to VW_WobQueryCreate( )

• FieldName

An empty string ("“) you provide as a place-holder for the Work Ob-
ject ID

or

“F_WobNum” to search for a Work Object by its Work Object num-

ber

• Value (the Work Object ID or Work Object number)

User-defined in the Work Class

Work Object number (as a string), if you are searching for a Work
Object by its number

This sets the Work Object ID or number into WobQueryHandle.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 464

 4 Application Programming Interface
VW_WobQueryCreate

Access specific Work Objects in a Work Class

WorkClassName

VW_WobQueryCreate( )

WobQueryHandle FieldName Value

("“ or “F_WobNum”) (Work Object ID or number)

VW_SetString( )
Work Object ID or number

QueryCountLimit WobQueryHandle

VW_WobQueryExecute( )

QueryCount

3 Call VW_WobQueryExecute( ).

If you called a data access API (steps 1 and 2), the following occur:

• VW_WobQueryExecute( ) receives a WobQueryHandle that speci-

fies to match and count Work Objects that meet both of these crite-
ria:

- They are in the Work Class you name in WorkClassName.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 465

 4 Application Programming Interface
VW_WobQueryCreate

- They have the Work Object ID or Work Object number set into
WobQueryHandle by VW_SetString( ).

• Visual WorkFlo counts—up to the maximum number you specify

with QueryCountLimit input to VW_WobQueryExecute( )—all of the
Work Objects in the class that have the Work Object ID or number.

Otherwise, the following occur:

• WobQueryHandle specifies only the Work Class name you input

as WorkClassName to VW_WobQueryCreate( ).

• VW_WobQueryExecute( ) counts all of the Work Objects, up to the

maximum number you specify in its QueryCountLimit input to VW_
WobQueryExecute( ).

It outputs the number it counts as QueryCount .

Access all Work Objects in a Work Class

WorkClassName

VW_WobQueryCreate( )

WobQueryHandle WobQueryHandle

QueryCountLimit

VW_WobQueryExecute( )

QueryCount

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 466

 4 Application Programming Interface
VW_WobQueryCreate

4 Call VW_WobQueryEnd( ) to free resources associated with

WobQueryHandle.

C typedef typedef VW_Error(VWAPIENTRY *VW_WobQueryCreateProcType)

(VW_LogonHandle,
VW_ClassNameType FAR,
VW_WobQueryHandle FAR *);

Example:
See “Administrative Application Development” on page 64 for sample
code.

See Also:
“VW_WobQueryEnd” on page 468

“VW_WobQueryExecute” on page 469

The Visual WorkFlo/Composer Handbook for more information on

specifying a Work Object ID in a Work Class definition

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 467

 4 Application Programming Interface
VW_WobQueryEnd

VW_WobQueryEnd
ErrorCode = VW_WobQueryEnd (WobQueryHandle)

Visual Basic
Object Browser
Input Data Type Source
WobQueryHandle long VW_WobQueryCreate( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API invalidates WobQueryHandle and frees the resources associ-
ated with it. Call it to release resources allocated by VW_
WobQueryCreate( ).

C typedef typedef VW_Error (VWAPIENTRY *VW_WobQueryEndProcType)

(VW_WobQueryHandle);

See Also:
“VW_WobQueryCreate” on page 463

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 468

 4 Application Programming Interface
VW_WobQueryExecute

VW_WobQueryExecute
ErrorCode = VW_WobQueryExecute (WobQueryHandle,
QueryCountLimit, QueryCount)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WobQueryHandle long VW_WobQueryCreate( )
or
VW_SetXXX( )a

QueryCountLimit long Developer

QueryCount long VW_WobQueryInstrSheet( )

VW_WobQueryOperation( )
VW_WobQueryWork
PerformerClass( )
VW_WobQueryGetWorkOb-
jectName( )
a. A data access API, such as VW_SetInteger( )

See “API Calling Sequence” on page 484 for context.

Summary This API executes the Work Object query that began with a call to VW_
WobQueryCreate( ). It matches and counts Work Objects, up to a de-
veloper-specified maximum. An index number resulting from the count
may be used in subsequent calls to APIs to find information on a spe-
cific Work Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 469

 4 Application Programming Interface
VW_WobQueryExecute

Result of Call This API matches and counts Work Objects identified by WobQuery-
Handle, up to the maximum number you specify in QueryCountLimit,
as follows:

Resulting Count
Specified by WobQueryHandle (output as QueryCount)
A Work Class name only All Work Objects in the Work Class
A Work Class name and a Work Ob- Work Objects that are in the Work Class
ject ID value that have a specific Work Object ID value
Please see “VW_WobQueryCreate” on
page 463 for information on inclusion of
the Work Object ID value.

Work Object Index Number

To use the resulting QueryCount to obtain information about one of
the counted Work Objects:

• Determine the Work Object’s index number in QueryCount.

The API assigns each Work Object an index number as it counts;

the Work Object of interest to you will have a index number of 0 to
QueryCount-1.

0 < index number < QueryCount-1

• Input its index number (as QueryCountIndex) to a subsequent call,

such as VW_WobQueryOperation( ), VW_
WobQueryWorkPerformerClass( ), or VW_WobQueryInstrSheet( ).

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 470

 4 Application Programming Interface
VW_WobQueryExecute

Limiting the Count

The number of matches found, QueryCount , is less than or equal to
QueryCountLimit:

QueryCount < QueryCountLimit

Specify QueryCountLimit = 0 for unlimited counting, but consider first

the additional system resources this may require.

Tips Before calling VW_WobQueryEnd( ), you can call this API repeatedly
to refresh the list of matching Work Objects.

C typedef typedef VW_Error (VWAPIENTRY *VW_WobQueryExecuteProcType)

(VW_WobQueryHandle,
unsigned int,
unsigned int FAR *);

See Also:
“VW_WobQueryCreate” on page 463

“VW_WobQueryGetWorkObjectName” on page 475

“VW_WobQueryInstrSheet” on page 477

“VW_WobQueryOperation” on page 479

“VW_WobQueryWorkPerformerClass” on page 481

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 471

 4 Application Programming Interface
VW_WobQueryGetAccessHandle

VW_WobQueryGetAccessHandle
ErrorCode = VW_WobQueryGetAccessHandle (WobQueryHandle,
QueryCountIndex, LockForUpdate, WobAccessHandle)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WobQueryHandle long VW_WobQueryCreate( )

QueryCountIndex long Developer, after a call to VW_

WobQueryExecute( )

LockForUpdate integer Developer

WobAccessHandle long VW_BindToUser( )

VW_FreeAccesHandle( )
VW_GetWobSignature( )

See “API Calling Sequence” on page 484 for context.

Summary This API returns an access handle to use in changing a Work Object,
with a call to a data access APIs, such as VW_GetInteger( ) or VW_
SetFloat( ).

Result of Call This API returns the access handle WobAccessHandle for use in sub-
sequent calls to the data access APIs when you want to change a
Work Object.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 472

 4 Application Programming Interface
VW_WobQueryGetAccessHandle

Work Object Identification

This API uses WobQueryHandle and QueryCountIndex to identify the
Work Object for which you want a handle, as follows:

• WobQueryHandle limits the query to certain Work Objects in a

Work Class. See “VW_WobQueryCreate” on page 463 for more in-
formation.

• In that limited query, you identify a particular Work Object by speci-

fying its index number in QueryCountIndex, obtained by a previous
call to VW_WobQueryExecute( ). See “Work Object Index Num-
ber” on page 470.

Security
A security error returns unless the logged-on user has access rights to
the Work Object and the queue. Results of the setting choice for Lock-
ForUpdate follow:

LockForUpdate = true (this is one: 1) LockForUpdate = false (this is zero: 0)

Subsequent attempts to obtain an The returned WobAccessHandle can
access handle for the same Work be used only to read fields from the
Object with the LockForUpdate pa- Work Object and the queue.
rameter fail until WobAccessHan-
dle is freed.
The user has read and write access The user has read-only access to the
to the roster and the queue. roster and the queue.

Tips After locking a Work Object with VW_WobQueryGetAccessHandle( ),

verify that it still fits the search criteria you specified when locating the
Work Object; the Work Object may change between the time you lo-
cate it and the time you lock it.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 473

 4 Application Programming Interface
VW_WobQueryGetAccessHandle

Call VW_FreeAccessHandle( ) when you finish with the access handle.

C typedef typedef VW_Error (VWAPIENTRY *VW_

WobQueryGetAccessHandleProcType)
(VW_WobQueryHandle,
unsigned int,
VW_Boolean,
VW_WobAccessHandle FAR *);

See Also:
“VW_BindToUser” on page 272

“VW_FreeAccessHandle” on page 300

“VW_GetWobSignature” on page 354

“VW_WobQueryCreate” on page 463

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 474

 4 Application Programming Interface
VW_WobQueryGetWorkObjectName

VW_WobQueryGetWorkObjectName
ErrorCode = VW_WobQueryGetWorkObjectName (WobQueryHan-
dle, QueryCountIndex, WorkObjectName)

Visual Basic
Object Browser
Input/Output Data Type Source
WobQueryHandle long VW_WobQueryCreate( )

QueryCountIndex long Developer, after a call to VW_

WobQueryExecute( )

WorkObjectName string

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in WorkObjectName the name of the Work Object
identified by WobQueryHandle, using QueryCountIndex as a match to
the Work Object query. Call VW_WobQueryExecute( ), prior to calling
this API, to determine the QueryCountIndex of the Work Object. See
“Work Object Index Number” on page 470.

The returned Work Object name is the human-readable-string equiva-

lent of the Work Object tag. (See “Work Object Identification” on
page 52 to compare the various forms of Work Object identity.)

C typedef typedef VW_Error (VWAPIENTRY *VW_

WobQueryGetWorkObjectNameProcType)
(VW_Handle,
unsigned int,
VW_WorkObjectNameType FAR);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 475

 4 Application Programming Interface
VW_WobQueryGetWorkObjectName

See Also:
“VW_WobQueryCreate” on page 463

“VW_WobQueryExecute” on page 469

Visual WorkFlo Technical Notes to compare the Work Object name

with the Work Object ID, the Work Object tag, and the Work Object
number

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 476

 4 Application Programming Interface
VW_WobQueryInstrSheet

VW_WobQueryInstrSheet
ErrorCode = VW_WobQueryInstrSheet (WobQueryHandle, Query-
CountIndex, InstructionSheetName)

Visual Basic
Object Browser
Input/Output Data Type Source
WobQueryHandle long VW_WobQueryCreate( )

QueryCountIndex long Developer, after a call to VW_

WobQueryExecute( )

InstructionSheetName string

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in InstructionSheetName the name of the Instruction
Sheet that Visual WorkFlo is executing to process the Work Object you
identify with QueryCountIndex.

Call VW_WobQueryExecute( ), prior to calling this API, to determine

the QueryCountIndex of the Work Object. See “Work Object Index
Number” on page 470.

WobQueryHandle specifies which Work Objects in a Work Class to in-

volve in the query. See “VW_WobQueryCreate” on page 463 for more
information.

C typedef typedef VW_Error(VWAPIENTRY *VW_WobQueryInstrSheetProcType)

(VW_WobQueryHandle,
unsigned int,
VW_InstrSheetNameType FAR);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 477

 4 Application Programming Interface
VW_WobQueryInstrSheet

See Also:
“VW_WobQueryCreate” on page 463

“VW_WobQueryExecute” on page 469

Getting Started with Visual WorkFlo for more information about In-
struction Sheets

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 478

 4 Application Programming Interface
VW_WobQueryOperation

VW_WobQueryOperation
ErrorCode = VW_WobQueryOperation (WobQueryHandle,
QueryCountIndex, OperationName)

Visual Basic
Object Browser
Input/Output Data Type Source/Destination
WobQueryHandle long VW_WobQueryCreate( )

QueryCountIndex long Developer, after a call to VW_

WobQueryExecute( )

OperationName string Data access APIa

a. An API such as VW_SetInteger( )

See “API Calling Sequence” on page 484 for context.

Result of Call This API returns in OperationName the name of the Operation that
will next process the Work Object you specify with QueryCountIndex.

Call VW_WobQueryExecute( ), to determine the QueryCountIndex of

the Work Object. See “Work Object Index Number” on page 470.

WobQueryHandle specifies which Work Objects in a Work Class to in-

volve in the query. See “VW_WobQueryCreate” on page 463 for more
information.

C typedef typedef VW_Error(VWAPIENTRY *VW_WobQueryOperationNameProcType)

(VW_WobQueryHandle,
unsigned int,
VW_OperationNameType FAR);

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 479

 4 Application Programming Interface
The APIs

See Also:
“VW_WobQueryCreate” on page 463

“VW_WobQueryExecute” on page 469

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 480

 4 Application Programming Interface
The APIs

VW_WobQueryWorkPerformerClass
ErrorCode = VW_WobQueryWorkPerformerClass (WobQueryHandle,
QueryCountIndex, WorkPerformerClassName)

Visual Basic
Object Browser
Input/Output Data Type Source
WobQueryHandle long VW_WobQueryCreate( )

QueryCountIndex long Developer, after a call to VW_

WobQueryExecute( )

WorkPerformerClass string
Name

See “API Calling Sequence” on page 484 for context.

Summary Use this API to determine which Work Queue a particular Work Object
is in.

Result of Call This API returns in WorkPerformerClassName the name of the Work
Performer Class associated with the Work Queue in which is the Work
Object you specify with QueryCountIndex .

This API uses the following input to identify the Work Object:

• QueryCountIndex of the Work Object

Call VW_WobQueryExecute( ) to obtain this. See “Work Object In-

dex Number” on page 470.

• WobQueryHandle

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 481

 4 Application Programming Interface
The APIs

This limits the query to certain Work Objects in a Work Class. See
“VW_WobQueryCreate” on page 463 for more information.

C typedef typedef VW_Error(VWAPIENTRY *VW_

WobQueryWorkPerformerClassProcType)
(VW_WobQueryHandle,
unsigned int,
VW_ClassNameType FAR);

See Also:
“VW_WobQueryCreate” on page 463

Return to “Locator” on page 242

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 482

 4 Application Programming Interface
VW_WobQueryWorkPerformerClass

The API Calling Sequence Chart begins on the following page.

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 483

Panagon Visual Workflo 3.0 To expand chart:
Select ‘View’ menu,
Application Developer’s Guide Continuous Facing Pages, Zoom to 65%

API Calling Sequence

CREATIVE ADMINISTRATIVE
“VW_LogonEx” on page 376
“VW_Logon” on page 373
LogonHandle

“VW_CreateWorkObject” on page 293 “VW_QsCreateQuerySpecifier” on page 403

NewWorkObjectHandle QuerySpecifierHandle

Go to
“Set Data” on page 492 Go to “Begin Queue Query” on page 490

“VW_LogQueryBegin” on page 381

LogQueryHandle

“VW_LogQueryNextRecords” on page 384

“VW_LogQueryEnd” on page 383

“VW_QsFreeQuerySpecifier” on page 414

Go to “Get Data” on page 493

“VW_DispatchWorkObject” on page 298

“VW_Logoff” on page 372

 API Calling Sequence
ACTIVE WORK PERFORMER

Go to
“Create Work Object Query” on page 491

“VW_GetErrorMessageSize” on page 325

“VW_GetErrorMessage” on page 324 “Attach to a Work Queue” on page 486

[Listed alphabetically:]
“VW_CheckVersionCompatibility” on page 291
“VW_GetClassFieldNames” on page 318
“VW_GetIsolatedRegion” on page 340
“VW_GetMachineId” on page 341
“VW_GetQueueNames” on page 346
“VW_GetWorkClassNames” on page 355
“VW_GetWorkPerformerClassNames” on page 361
“VW_GetWorkQueueDepth” on page 365
“VW_QueueGetStats” on page 415
“VW_RosterGetStats” on page 423
“VW_SequencedWait” on page 428
 ACTIVE WORK PERFORMER

Attach to a Work Queue

“VW_AttachToWorkQueue” on page 264

QueueHandle

“VW_BrmCreateBrowseModifier” on page 274

BrowseModifierHandle

“VW_BrmSetPreSelectRule” on page 279

“VW_BrmSetSelectRule” on page 281
“VW_BrmSetSortRules” on page 283
“VW_BrmSetLockFilter” on page 277

“VW_ReportToWork” on page 421

WorkPerformerHandle

“VW_BeginBrowsingWorkQueue” on page 267

BrowseSessionHandle

“VW_NextWorkObjectToBrowse” on page 388

QueueElementHandle

“VW_GetAccessHandle” on page 304

WobAccessHandle

“VW_GetWobSignature” on page 354

“VW_LockWorkObject” on page 367
OperationHandle
“VW_GetWobSignature” on page 354

“VW_BindToUser” on page 272

“VW_GetBindings” on page 314
“VW_UnBind” on page 460
 “VW_BindToUser” on page 272
“VW_GetBindings” on page 314
“VW_UnBind” on page 460

Go to “Set Data” on page 492

and “Get Data” on page 494

“VW_FreeAccessHandle” on page 300

“VW_GetOperationNameSize” on page 343

“VW_GetOperationName” on page 342

Go to “Get Data” on page 494

“VW_BrmFreeBrowseModifier” on page 276

“VW_EndBrowsingWorkQueue” on page 299

Go to “Sequenced Mode” on page 496

“VW_LogMessage” on page 370

Go to “Set Data” on page 492 and “Get Data” on page 493

“VW_LeaveWork” on page 366

“VW_DetachFromWorkQueue” on page 297

Return to “API Calling Sequence” on page 485

 Go to “Get Data” on page 494
“VW_GetParameterMode” on page 344

“VW_CurrentException” on page 295

“VW_UnlockWorkObject” on page 462

“VW_UnlockAndDispatch” on page 461

“VW_Call” on page 288

“VW_RaiseException” on page 419

“VW_TerminateWorkObject” on page 458

“VW_EndBrowsingWorkQueue” on page 299

“VW_GetWorkPerformerHandle” on page 364

WorkPerformerHandle

“VW_LogMessage” on page 370

Administrative Application

Begin Queue Query

“VW_QQueryBegin” on page 390
QueueQueryHandle

VW_QQ_WANT_TO_LOCK
specified in QueueQueryOptions? No

“VW_QQueryNextWorkObject” on page 401

Yes QueueElementHandle

“VW_LockWorkObject” on page 367

Go to “Get Data” on page 494

“VW_QQueryNextLockedWorkObject” on page 399

OperationHandle

Go to “Set Data” on page 492

and “Get Data” on page 494

“VW_UnlockAndDispatch” on page 461

“VW_QQueryEnd” on page 398

Return to “API Calling Sequence” on page 484

Administrative Application

Create Work Object Query

“VW_WobQueryCreate” on page 463
WobQueryHandle

Go to “Set Data” on page 492

“VW_WobQueryExecute” on page 469

[Listed alphabetically]
“VW_WobQueryInstrSheet” on page 477
“VW_WobQueryOperation” on page 479
“VW_WobQueryWorkPerformerClass” on page 481

“VW_WobQueryEnd” on page 468

“VW_WobQueryGetAccessHandle” on page 472

WobAccessHandle

“VW_BindToUser” on page 272

“VW_GetBindings” on page 314
“VW_UnBind” on page 460

“VW_GetWobSignature” on page 354

Go to “Get Data” on page 494 and “Set Data” on page 492

“VW_FreeAccessHandle” on page 300

Return to “API Calling Sequence” on page 485

All Application Categories

Set Data
[Listed Alphabetically]
“VW_SetArray” on page 439
“VW_SetArrayPtr” on page 441
“VW_SetBoolean” on page 444
“VW_SetField” on page 446
“VW_SetFloat” on page 448
“VW_SetFPNumber” on page 450
“VW_SetInteger” on page 452
“VW_SetTime” on page 456
“VW_SetString” on page 454

Return to:

“API Calling Sequence” on page 484 for NewWorkObjectHandle

“Create Work Object Query” on page 491 for WobQueryHandle and

WobAccessHandle

“Attach to a Work Queue” on page 486 for WorkPerformerHandle, Op-

erationHandle, and WobAccessHandle

“Begin Queue Query” on page 490 for OperationHandle

“Sequenced Mode” on page 496 for OperationHandle

Administrative Application or Work Performer

Get Data

“VW_GetFieldNames” on page 330

“VW_GetField” on page 326

“VW_GetArraySize” on page 312

“VW_GetArrayPtr” on page 309
“VW_FreeArrayPtr” on page 303

“VW_GetStringSize” on page 350

“VW_GetString” on page 348

[Listed alphabetically]
“VW_GetArray” on page 307
“VW_GetBoolean” on page 316
“VW_GetDataType” on page 320
“VW_GetDataTypeArray” on page 322
“VW_GetFieldNames” on page 330
“VW_GetFloat” on page 334
“VW_GetFPNumber” on page 336
“VW_GetHandleType” on page 338
“VW_GetInteger” on page 339
“VW_GetTime” on page 352

Return to
“API Calling Sequence” on page 484 (NewWorkObjectHandle)
“Attach to a Work Queue” on page 486 (WorkPerformerHandle)
Administrative or Active Work Performer Application

Get Data

“VW_GetFieldNames” on page 330

“VW_GetField” on page 326

“VW_GetArraySize” on page 312

“VW_GetArrayPtr” on page 309
“VW_FreeArrayPtr” on page 303

“VW_GetStringSize” on page 350

“VW_GetString” on page 348
[Listed alphabetically]
“VW_GetArray” on page 307
“VW_GetBoolean” on page 316
“VW_GetDataType” on page 320
“VW_GetDataTypeArray” on page 322
“VW_GetFieldNames” on page 330
“VW_GetFloat” on page 334
“VW_GetFPNumber” on page 336
“VW_GetHandleType” on page 338
“VW_GetInteger” on page 339
“VW_GetTime” on page 352
“VW_GetWorkObjectLockStatus” on page 357
“VW_GetWorkObjectName” on page 359

Return to sequence (see facing page)

Administrative or Active Work Performer Application

Get Data (continued)

Return from Get Data on the facing page:

“Begin Queue Query” on page 490 (OperationHandle and QueueEle-

mentHandle)

“Create Work Object Query” on page 491 (WobAccessHandle)

“Attach to a Work Queue” on page 486 (WobAccessHandle,

QueueElementHandle, and OperationHandle)
Sequenced Mode

“VW_SequencedWobFetch” on page 437

Go to “Set Data” on page 492 and “Get Data” on page 493

“VW_UnlockAndDispatch” on page 461

“VW_EndBrowsingWorkQueue” on page 299

“VW_LeaveWork” on page 366

“VW_DetachFromWorkQueue” on page 297

“VW_Logoff” on page 372

Return to “Attach to a Work Queue” on page 486

 Index

A API pairs 253

active Work Performers API task groups 254
when to use 36 client-side designs 34
writing as OLE server 167 data access APIs 260
adaptors debugging 177
C data type conversions 164 designing 33
administrative VW application error handling APIs 261
creating 64 in SCVAPI.H file 242
application logging and debugging APIs 255
category of 24 OLE automation, using 40, 42, 44
application programming interface functions SAFEARRAY array, using 47
(APIs) server-side 187
callling sequence by category server-side designs 34
(chart) 252 server-side directories 189
application programming interfaces syntax for 45, 50
(APIs) 181, 253 UNIX and Windows comparison 192, 215
calling sequences for 45 validation checking 185
calling VW_Logon 241 wal_purge usage 184
data access APIs 260 Work Object access APIs 259
error handling APIs 261 Work Object binding APIs 259
in SCVAPI.H file (table) 242 Work Object creation APIs 255
logging APIs 255 as-is business processes 18
SAFEARRAY array, using 47 AutoClaim application
success status 49 developing business processes 23
task groups 254 development overview 23
Work Object access APIs 259 automated business processes
Work Object binding APIs 259 tools for 17
Work Object creation APIs 255
applications B
administrative, creating 64 business processes
as-is 18

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 497

 Index

automated 17 converting to C for passive Work

choosing Work Performer types 34 Performers 164
developing applications 23 using OLE automation 46
example high-volume site 20 using VW for OLE wrappers 47
low-volume site example 20 VARIANT, for OLE server interfacing 47,
process mapping for 38 48
to-be 20 debugging applications
to-be, for remote 22 APIs for 255
designing 177
C NDump Work Performer 178, 179
C language designing
converting data types for passive Work applications 33
Performers 164 choosing Work Performer types 34
DLLs and passive Work Performers 163 client-side applications 34
VW_VariantArray type 47, 48 server-side applications 34
C++ language direct OLE automation interface 47
DLLs and passive Work Performers 163 DLL adaptor
calling sequence data returned from passive Work
API calls by category (chart) 252 Performers 165
category, of VW application 24 DLL wrapper
client software interfacing with OLE automation 46
areas to install 188 using VW_ data types 47
compilation script
for server-side conversions 189 E
Composer error handling
Work Performers, setting up 145 APIs for 261
conversions exception handling
client-side to server-side 189 validation checking 185
customizing exposed fields
workflow views 39 performance implications 184
D G
data access granularity
APIs for 260 Work Performer Operations 185
data types Guide

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 498

 Index

when to use 13 registering 147

who uses 12 writing passive Work Performers 148
Operations
H granularity of 185
Handle, identifiying 50 parameter tracking 183
handles reusability 182
API input 49
high-volume sites P
example business process 20 pairs, UI button for 181
parameter tracking operations 183
I passive Work Performers
inout parameters, passing results 166 converting C data types 164
L converting to OLE automation client 147
logging OLE server, using 148
APIs for 255 registering 147
logon ID, using LogonHandle 49 returning data to DLL adaptor 165
LogonHandle 49 using VWDLLADP adaptor 163
low-volume site when to use 35
example business process 20 performance and field exposure 184
process mapping
M automating the business process 38
memory allocation
deallocating after call returns 166 R
registering OLE servers 147
N related groups 253
NDump Work Performer 178, 179 returning logon ID 49
reusability
O
Work Performer Operations 182
OLE automation
robot tasks
data type accessing 46
example business process 20
using a DLL wrapper 46
using applications in 40, 42, 44 S
OLE clients SAFEARRAY array 47
using passive Work Performers 147 SCVAPI.H file
OLE server applications in (table) 242
active Work Performers for 167

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 499

 Index

security VW_Call API 288

controlling access to applications 54 VW_CheckVersionCompatibility API 291
sequence VW_CreateWorkObject API 293
API calls by category 252 VW_CurrentException API 295
sequence processing VW_DetachFromWorkQueue API 297
API calls by category 45 VW_DispatchWorkObject API 298
determined by user 38 VW_EndBrowsingWorkQueue API 299
predetermined by developer 37 VW_FreeAccessHandle API 300
servers VW_FreeArrayPtr API 303
client software on 188 VW_GetAccessHandle API 304
server-side applications 187 VW_GetArray API 307
success status VW_GetArrayPtr API 309
for API calls 49 VW_GetArraySize API 312
VW_GetBindings API 314
T VW_GetBoolean API 316
to-be business processes 20 VW_GetClassFieldNames API 318
remote site (example) 22 VW_GetDataType API 320
U VW_GetDataTypeArray API 322
UI button for API pairs 181 VW_GetErrorMessageSize API 325
UNIX VW_GetField API 326
contrasting Windows application 192, VW_GetFieldNames API 330
215 VW_GetFieldSize API 332
VW_GetFloat API 334
V VW_GetFPNumber API 336
validation checking 185 VW_GetHandleType
VW_AttachToWorkQueue API 263, 264 handle type, returning 50
VW_BeginBrowsingWorkQueue API 267 VW_GetHandleType API 338
VW_BindToUser API 272 VW_GetInteger API 339
VW_BrmCreateBrowseModifier API 274 VW_GetIsolatedRegion API 340
VW_BrmFreeBrowseModifier API 276 VW_GetMachineId API 341
VW_BrmSetLockFilter API 277 VW_GetOperationName API 342
VW_BrmSetPreSelectRule API 279 VW_GetOperationNameSize API 343
VW_BrmSetSelectRule API 281 VW_GetParameterMode API 344
VW_BrmSetSortRules API 283 VW_GetQueueNames API 346

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 500

 Index

VW_GetString API 348 VW_SequencedWait API 428

VW_GetStringSize API 350 VW_SequencedWobFetch API 437
VW_GetTime API 352 VW_SetArray API 439
VW_GetWobSignature API 354 VW_SetArrayPtr API 441
VW_GetWorkClassNames API 355 VW_SetBoolean API 444
VW_GetWorkObjectLockStatus API 357 VW_SetField API 446
VW_GetWorkObjectName API 359 VW_SetFloat API 448
VW_GetWorkPerformerClassNames VW_SetFPNumber API 450
API 361 VW_SetInteger API 452
VW_GetWorkPerformerHandle API 364 VW_SetString API 454
VW_GetWorkQueueDepth API 365 VW_SetTime API 456
VW_LeaveWork API 366 VW_TerminateWorkObject API 458
VW_LockWorkObject API 367 VW_UnBind API 460
VW_LogMessage API 370 VW_UnlockAndDispatch API 461
VW_Logoff API 372 VW_UnlockWorkObject API 462
VW_Logon VW_VariantArray type 47, 48
VW applications 241 VW_WobQueryCreate API 463
VW_Logon API 373 VW_WobQueryEnd API 468
VW_LogonEx API 376 VW_WobQueryExecute API 469
VW_LogQueryBegin API 381 VW_WobQueryGetAccessHandle API 472
VW_LogQueryEnd API 383 VW_WobQueryGetWorkObjectName
VW_LogQueryNextRecords API 384 API 475
VW_NextWorkObjectToBrowse API 388 VW_WobQueryInstrSheet API 477
VW_QQueryBegin API 390 VW_WobQueryOperation API 479
VW_QQueryEnd API 398 VW_WobQueryWorkPerformerClass
VW_QQueryNextLockedWorkObject API 481
API 399 VWDLLADP adaptor
VW_QQueryNextWorkObject API 401 passive Work Performer
VW_QsCreateQuerySpecifier API 403 communication 163
VW_QsFreeQuerySpecifier API 414
W
VW_QueueGetStats API 415
VW_RaiseException API 419 W_GetErrorMessage API 324
VW_ReportToWork API 421 wal_purge utility, in applications 184
VW_RosterGetStats API 423 Windows
constrasting UNIX application 192, 215

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 501

 Index

Work Objects
accessing, APIs for 259
binding, APIs for 259
creating (example) 56
creating, APIs for 255
customizing 28
Work Performers
active
for OLE servers 167
opting for 36
choosing passive or active 34
Composer set up 145
Operation reusability 182
passive
converting to OLE automation
client 147
opting for 35
returning data to DLL adaptors 165
VWDLLADP adaptor usage 163
writing to OLE server 148
Work Queue fields
number of 184
WorkFlo Application Library (WAL)
memory areas of 189
workflow view
customizing 39

August 1998 Panagon Visual WorkFlo Application Developer’s Guide 502