Vantive API: Reference Guide

Vantive API
Reference Guide

Vantive Publication Number: 7850-700-####-H
The Vantive Corporation 2455 Augustine Drive Santa Clara, CA 95054 Phone: (408) 982-5700 Fax: (408) 982-5710
Printed: 1997 Information in this guide is subject to change without notice and does not constitute a commitment on the part of The VANTIVE Corporation. It is supplied on an as is basis without any warranty of any kind, either explicit or implied. Information may be changed or updated in this guide at any time.

Copyright 1997 THE VANTIVE CORPORATION AND ITS LICENSORS. ALL RIGHTS RESERVED. No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner, THE VANTIVE CORPORATION. Copyright infringement is a serious matter under the United States and foreign copyright laws. The copyrighted software that accompanies this manual is licensed to the End User for use only in strict accordance with the End User License Agreement which License should be read carefully as it governs the use of software in this manual. Information in this document is subject to change without notice and does not represent a commitment on the part of The Vantive Corporation. THE INFORMATION AND MATERIAL CONTAINED IN THIS MANUAL ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION AND WARRANTY CONCERNING THE ACCURACY, ADEQUACY, OR COMPLETENESS OF SUCH INFORMATION OR MATERIAL OR THE RESULTS TO BE OBTAINED FROM USING SUCH INFORMATION OR MATERIAL. THE VANTIVE CORPORATION SHALL NOT BE RESPONSIBLE FOR ANY CLAIMS ATTRIBUTABLE TO ERRORS, OMISSIONS OR OTHER INACCURACIES IN THE INFORMATION OR MATERIAL CONTAINED IN THIS MANUAL, AND IN NO EVENT SHALL THE CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF SUCH INFORMATION OR MATERIAL, REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT PRODUCT LIABILITY OR OTHERWISE, EVEN IF THE VANTIVE CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Printed in the United States of America. Vantive Enterprise, Vantive HelpDesk, Vantive Quality, Vantive Sales, Vantive FieldService, Vantive Support are trademarks of The Vantive Corporation. Names marked or and other company and product names may be trademarks or registered trademarks of their respective vendors or organizations.
Table of Contents

1 Vantive API Installation

! " #
! # $ !! %# # & '

!! %# # "
(
!) %# # " "
!* %# #

!+ %# # &
# !+ %# # &
!, %# # ( -

!. & #

!. & # / %
#
!0 1
) 1
)! " ( 1
)) & '
1
)* ( -
1
)+ 1
)+ " "

),
2 Vantive API Function Categories
3 Vantive API Language Elements
Vantive API Reference Guide
Table of Contents

). 2
#
)0 2
#
).
4 Function Descriptions
& 3 4 * * &

*! 5 ( 3 4 *) ** &
*+
3 4 *, *. &
*0
3 4 *6 *6 &
*7

3 4 * *! &
*!
/ 3 4 *) *) &
**
"3 4 *+ *, &
*. 1
"3 4 *0 *0 &
*6 "3 4 *!7 *! &
*!! "3 4 *!) *!* &
*!*
ii
Table of Contents
"3 4 *!, *!, &

*!. % "3 4 *!0 *!6 &
*!6 &-
3 4 *)7 *) &
*)! "3 4 *)) *)* &
*)* "3 4 *), *), &
*). & 3 4 *)0 *)0 &
*)6 3 4 ** ** &
**! &
3 4 **) **) &
*** /- 3 4 **+ **, &
**. /- 3 4 **0 **0 &
**6 /- %- #3 4 *+7 *+ &
*+ /8 3 4 *+) *+)
Vantive API Reference Guide iii
Table of Contents
&

*+) " & 3 4 *++ *+, &
*+, "
3 4 *+0 *+0 &
*+6 " (-
3 4 *, *, &
*, 3 4 *,! *,! &
*,) 8 3 4 *,* *,+ &
*,+ 3 4 *,0 *,0 &
*,6 3 4 *. *. &
*.! " 3 4 *.* *.* &
*.+ ( 3 4 *., *.. &
*.0 (-
*.6 *07 &
*0! - (3 4 *0) *0) &
*0* %
#3 4 *0+
iv Vantive API Reference Guide
Table of Contents
*0+ &

*0, 8 9& 3 4 *0. *0. &
*00 8
3 4 *06 *06 &
*67 8"
3 4 *6 *6 & *6 : 3 4 *6! *6! &
*6) :
3 4 *6* *6+ &
*6, : / 3 4 *6. *60 &
*60 3 4 *77 *7 &
*7 3 4 *7) *7) &
*7* &
3 4 *7, *7. &
*7. &
(-
*70 *76 &
*76 & 3 4 *7 * &
*!
Vantive API Reference Guide v
Table of Contents
3 4 *) ** &

** 3 4 *, *. &
*0 " 3 4 *6 *!7 &
*! 3 4 *!! *!) &
*!) 2#
3 4 *!* *!+ &
*!,
A Vanperl Extensions
" /'

& 3 4 ! 5 ( 3 4 !
3 4 )
3 4 *

3 4 *
/ 3 4 +
"3 4 + 1
"3 4 , "3 4 , "3 4 . "3 4 . % "3 4 0 &-
3 4 0 "3 4 6 "3 4 6 & 3 4 6
vi
Table of Contents
3 4 7 &

3 4 7 /- 3 4 /- 3 4 /- %- #3 4 /8 3 4 ! " & 3 4 ! "
3 4 ) 8 3 4 ) 3 4 * 3 4 * " 3 4 + - (3 4 + %
#3 4 , 8 9& 3 4 , 8
3 4 . 8"
3 4 . : 3 4 0 :
3 4 0 : / 3 4 6 3 4 6 3 4 6 &
3 4 !7 & 3 4 !7 3 4 ! 3 4 ! " 3 4 !! 3 4 !) 2#
3 4 !) !)
vii
Table of Contents
viii
Preface

The Vantive API Reference Guide explains how to install and use Vantive API to its fullest capabilities.
0

Vantive is the leader in Customer Asset Management. In order for us to better serve our customers needs, any and all comments and suggestions regarding this or any of our guides and manuals are welcome and can be sent to: docs@vantive.com.
Additionally, all current Vantive documentation can be accessed from the support area on the Vantive website at: http://www.vantive.com
Vantive. Because Customers Are Your Most Valuable Asset
ix
Preface

Some or all of the following conventions appear in this guide:

Bold alternate color a new term

...called a source object.
(online only) hotlinked cross- ...see Chapter 3, Data references to other sections in Migration. this guide; if you are viewing this guide online in PDF format, you can click the crossreference to jump directly to its location words that are emphasized the titles of other documents syntax variables ...the entry after the current entry... Vantive HelpDesk Installation Guide
COPY filename
Italic
Monospace
directories, file names, command names, computer code computer screen text, system responses, command line commands
&HPRICVL.SRCLIB
Copy file? Y/N
Monospace bold
what the user types the name of a key on the keyboard
...enter RUN.roi in the Application field Press <Enter>.
<>
Preface

Warning symbol. The bold text following indicates a warning.

Important. The bold text following indicates pertinent information.
Information. The bold text following indicates applicable references.
xi
Preface

xii

Vantive API installs with the Vantive System media. Please refer to your Installation Guide for your RDBMS for information concerning installation and maintenance.

Vantive API supports the following compilers.

Compilers that conform to the Solaris object format:

C Compiler GNU CC Sun C++

Microsoft Visual C++ 4.x Microsoft Visual C++ 5.0
1-1
Vantive API Installation

Vantive API requires certain shared libraries to reside in specific directories. These libraries vary depending on your platform. Refer to the README file from the VanAPI media for more information. When you install Vantive API in the Solaris environment, the Vantive files go in two directories named vanapi and vanperl. The file content of these directories are as follows:

vanapi.so vanapi.h example1.c example2.c example3.c
1-2
!
" #
The Vantive API is a set of functions that establish a connection with the Vantive server and manipulate the data in a Vantive application database. To do this, Vantive API functions perform the following tasks:
Start or terminate a connection with a Vantive server host and port. Create, modify, and execute Action Requests. An Action Request is a message you use to ask someone to carry out a task related to a Case.
The API functions fall into nine categories. Each category is based on the kinds of tasks performed by its functions.
" #
A Vantive API application begins by establishing a connection to a Vantive server. Once the connection is established, the application can use the Vantive API functions to perform form-based tasks that access, modify, and distribute your data.
2-1
Vantive API Function Categories

#

Before your Vantive API application can access the information stored in your database, the application must establish a connection to a Vantive server. Once the connection is established, other Vantive API functions can reference it with its connection handle, a 4-byte integer value that identifies the connection. When the server connection is no longer needed your application can close it, freeing the connection handle and any other resources that were used to maintain the connection. There are two Vantive API functions concerned with opening and closing server connections:

VanOpenConnection( )

Opens a connection to a Vantive server host and port. Creates a connection handle value that other API functions use to reference the connection. Closes a connection to a Vantive server.Frees the connection handle and any other resources used by the connection.
VanCloseConnection( )
$# # % &

Vantive API includes several functions that create, modify, execute, or cancel Action Requests. The Action Requests may be of the inbox type or the email type. Here are the steps required to prepare and send an Action Request:
2-2

1. Create a new Action Request using the
VanPrepareAction( )function. Creating an Action Request generates an action request handle, a 4-byte integer value used by other API functions to reference the Action Request.
2. Use the VanAddActionReceiver( )function to add
one or more recipients to the recipient list of the Action Request.

3. If necessary, modify the Action Request with the
VanSetActionProperty( )function.
4. If necessary, execute the Action Request using the

VanDoAction( )function. Otherwise, cancel the Action Request with the VanStopAction( ) function.
Executing either function frees the action request handle and other resources associated with the Action Request.

VanPrepareAction( )

Starts a new Action Request. Creates an action request handle value that other API functions use to reference the action request. Modifies a property of an Action Request. Adds a recipient name to the list of recipients for an Action Request. Executes an Action Request. Cancels an Action Request that is currently prepared for execution.
VanSetActionProperty( ) VanAddActionReceiver( ) VanDoAction( ) VanStopAction( )
$# #"
'
Forms are the most important objects for data access in the Vantive system. Vantive API includes several functions that create forms and evaluate any subforms associated
2-3

with them. Creating a form generates a form handle, a 4byte integer value used by other API functions to reference the form. When the form no longer serves a purpose, you can close the form, freeing its form handle and any other resources associated with the form.

VanCreateInboxForm( )

Opens the inbox for the current user and prepares it for subsequent data access.Creates a form handle value that other API functions use to reference the inbox. Closes a currently open form.Frees the form handle and any other resources used by the form. Obtains the number of subforms available for an Information form. Obtains information about a subform of an Information form.
VanCloseForm( )
VanNumChilds( ) VanChildDesc( )
$# #""
Vantive API includes several functions that evaluate form fields, retrieve their data, or change their content.

VanNumFields( ) VanFieldDesc( ) VanSetField( )

Obtains the number of fields in an active form. Obtains selected information from a field in a form. Changes the contents of a form field.
2-4

VanGetField( )
Copies data from a form field to a variable.
$# #

When you use a form to access information in a database, you must create a database cursor to access individual records. Vantive API includes four functions that create, define, and manage cursors.

VanOpenCursor( )

Opens a cursor for an Information form, a subform, or an inbox form, thus preparing the form for subsequent fetch operations. Adds a field qualification to be used in a search. Retrieves a record from the Vantive server and displays its data in form. Closes an open cursor associated with a form. Obtains the number of records (the size of the data set) that the current cursor returns.
VanAddQualifier( ) VanFetchRecord( ) VanCloseCursor( ) VanSearchCount( )
$# # %
#
There are four functions that manage the Research Agent, a feature that designs and performs indexed keyword searches across character and text fields.

VanCloseExtDocument( )

Closes the document handle and frees up resources held during a document retrieval.
2-5

VanCreateRaList( )
Prepares a form handle for the object type specified by the order number of the position integer. Performs a Research Agent search operation and returns the number of object types found in the result list. Returns the total number of lines in the retrieved document. Returns the maximum length of any line in the retrieved document. Retrieves the document name as identified by the Research Agent. Returns the external document identification value. Retrieves a text line for the document opened by the function VanOpenExtDocument( ). Initiates access to an external document from the Research Agent server.
VanDoResearch( )
VanExtDocLineCount( ) VanExtDocMaxLineLength( ) VanExtDocName( ) VanGetDocId( ) VanExtDocLine( )
VanOpenExtDocument( )
$# #%
Vantive API includes four functions that evaluate changes in records, commit or discard those changes, or create new records.

VanNewRecord( ) VanSaveRecord( )

Creates a new record for a form and fills the record with default values. Saves the record that currently resides in a form.
2-6

VanUndoChanges( )
Undoes all changes to an existing record if it was changed with VanSetField( )and not saved, or discards the record altogether if it was created with VanNewRecord( ) and not saved. Determines if a record contains modified, unsaved data.
VanRecordStatus( )
$# #'(

There are four functions that manage info lists. An info list can contain information about inboxes or action receivers.

VanFreeInfoList( )

Removes an info list from memory and frees the resources previously used by the list. Returns an individual item from an info list and moves the pointer to the next item in the list. Starts an info list in memory andcreates an info list handle for use by the VanFreeInfoList( ), VanGetInfoItem( ), and VanRestartInfoList( ) functions. Sets the pointer back to the first item in the info list.
VanGetInfoItem( )
VanGetInfoList( )
VanRestartInfoList( )
% #

It is sometimes necessary to detect version differences between various elements of the Vantive system, including Vantive API itself. For this purpose, Vantive API includes the VanGetLibInfo( )function, which retrieves the version numbers of:
2-7

the client library the Vantive server the Vantive database dictionary Vantive API
All versions returned by the VanGetLibInfo( ) function apply to items of the Vantive system that are in use by the current Vantive server connection.
% #)$
#
When executing a Vantive API function that results in an error, an error message is generated. The VanGetMsg( )function retrieves the error message (if any) reported by the last Vantive API function call.
2-8
*
(## )
This chapter describes the fundamental language elements used by the Vantive API functions. These language elements fall into three categories:

Handle values Form Fields and Column Paths Vantive API Structures Vantive Predefined Variable Types
+
In the course of its activities, a Vantive API application creates and utilizes any of the following items:

A connection to a Vantive server host and port Forms or subforms in which data accessed by the Vantive server are displayed Action requests to be sent to receivers inboxes Info lists, which contain items that identify available inboxes or action receivers
3-1
Vantive API Language Elements
A document, which contains information external to your Vantive database
When a Vantive API function creates one of these items, it generates a handle, a number that identifies the item for other API functions. For example, each time you open a connection to a Vantive server, a handle value that identifies the connection is created automatically. You use this connection handle later when you create an Information form to access the servers data. Each handle is a 4-byte integer (long) value between 0 and 2147483647, inclusive. If the client application is written in C or C++, the handle variable must be declared as long. If the language is Visual Basic, the handle variable must be declared as Long.
+
Before your application can communicate with a Vantive server, it must establish a connection to the server with the VanOpenConnection( ) function. This function generates a connection handle, which is usually stored in a memory variable, as with: conn = VanOpenConnection(1L, &cr) You use this handle later to identify the connection for other Vantive API functions such as VanCreateMainForm( ), as with:
form = VanCreateMainForm(conn, CASE)
The server connection and the handle that identifies it are maintained until one of two things occurs: A disconnect error occurs due to a network or server problem. The application calls the VanCloseConnection( ) function.
3-2
"'+
Forms are the most important objects used by a Vantive API program. A form serves as a template in which a data record is displayed and manipulated. It defines field accessibility, default field values, and other rules that apply when your application manipulates the database. Each form you create with Vantive API is an instance of a form definition that is stored in the Vantive database dictionary. Vantive API includes two functions that create forms:
VanCreateInboxForm( ) This function creates an inbox form for receiving Action Requests. For example, the following command creates an inbox form named MInb: inbox = VanCreateInboxForm(conn, MInb) The handle for the new inbox form is stored in the variable named inbox.
VanCreateMainForm( ) This function creates an Information form for a particular object type. For example, the following command creates an Information form for case records: mform = VanCreateMainForm(conn, CASE) The handle for the new Information form is stored in the variable named mform.
Once you create a form handle, you can use it to reference the form with other Vantive API functions. An example is the VanGetField( )function, which retrieves a value from a field in a form:
3-3
VanGetField(mform, swSubject, &d) The maximum number of forms that can be active at one time is 16.
% &

+
A Vantive API program can create new Action Requests that perform any of the following actions:

Send a new inbox action request to a recipients inbox. Forward existing inbox Action Requests to a recipients inbox. Mark inbox action requests as done. Mark inbox action requests as cancelled.
Each Vantive API function that modifies or uses an Action Request requires a handle value to identify the Action Request. You generate this handle with the VanPrepareAction( ) function.For example, the following command creates a new Action Request and an action request handle that identifies it: action = VanPrepareAction(form, VAN_ASEND) The action request handle is stored in the variable action. (The form must contain a valid object record before an action can be created.) Once you create an action request handle, you can use it to reference the Action Request with another Vantive API functions such as VanDoAction( ): VanDoAction(action)
3-4
'(
+
An info list consists of a list, contained in memory, of inboxes or action receivers. You use the VanGetInfoList( ) function to start the info list and generate a handle value that allows other functions to access the list. For example, the following command creates an info list of all available inboxes and generates a handle variable named info for accessing the list: info = VanGetInfoList(conn, VAN_GINBOX, VAN_GDALL); An example of a function that uses the info list handle is the VanGetInfoItem( ) function, which retrieves individual items from the list: status = VanGetInfoItem(info, &d); Another example is the VanFreeInfoList( )function, which uses the info list handle to remove the list from memory: VanFreeInfoList(info); The maximum number of list handles that can exist at one time is 8.
+
Vantive API offers a function named VanOpenExtDocument( ) that can access external documents. Each time you call this function successfully, it generates a handle value. Your programs use this handle value to reference the document. For example, the following command accesses an existing document and creates a document handle named status: status = VanOpenExtDocument(conn, docId, 1L)
3-5
Later, you might use VanExtDocLine( ) to retrieve a text line from the document. status = VanExtDocLine(doc, 1L, &data)
""

Programs written with Vantive API often access and manipulate data displayed in form fields. You specify a particular form field by a column path, a Vantive language element that identifies the fields associated column in the database. When a Vantive function refers to a column belonging to the base table, the column path consists of the column name only. For example, if the value contained in a form field is a base table column named swLastName, the column path that references the column and its associated form field is simply: swLastName When a Vantive function refers to a column belonging to a foreign table, the column path must reference the foreign key, the foreign table, and the foreign table column that is displayed in the form field. For example, if the swLastName column exists in a foreign table named SW_PERSON, the following column path references the column: swReportedBy|SW_PERSON.swLastName
where swReportedBy is the foreign key linked with the primary key of the SW_PERSON table. (The primary key of the foriegn table is never included in the column path.)
3-6
One of the Vantive functions that use column paths to reference form fields is VanGetField( ), which retrieves the current contents of a form field. For example, the following function call retrieves data stored in a form field associated with a base table column named swSubject: VanGetField(form, swSubject, &d) The following function call retrieves information from a form field associated with a foreign table column named swTF: VanGetField(form, swKFld|SW_TABLX.swTF, &d) where swKFld is the foreign key linked with the primary key of a table named SW_TABLX.

When you call a Vantive API function, the arguments you specify for the function determine how the function executes. Some Vantive API functions use arguments that consist of predefined structures. The values contained in these structures fall into two categories:
Input values An input value provides information the function uses to perform its tasks correctly. For example, the second argument required by the VanOpenConnection( ) function (&cr in the example below) points to a structure (VanConnRecord) containing the information required to start a connection with a Vantive server: conn = VanOpenConnecton(1L, &cr) The VanConnRecord structure contains only the information needed to open the connection, such as user name and password. It does not contain any
3-7
values generated by the function, so it contains input values only. (Vantive API Structures are described below.)
Output values An output value is an item of information obtained by executing a function. For example, the last argument required by the VanGetField( ) function (&Data in the example below) points to a structure (VanData): VanGetField(form, swSubject, &Data) Many of the Vantive API functions that use such input and output values require that you specify the data type of those values. You specify data types with the predefined Vantive API data types (described below).
,
#
Vantive API structures contain input items that determine the way API functions operate, and output items that receive generated values.
#
Before your application can access information in a database, it must log on to a Vantive server host and port using the VanOpenConnection( )function. This function uses the VanConnRecord structure to provide the necessary login information. The values contained in the VanConnRecord structure are for input only; that is, no values generated by VanOpenConnection( ) are passed to any of the structures elements for later use. For a C/C++ program, the VanConnRecord structure contains four items:
3-8
struct VanConnRecord { char *crName; char *crPassword; char *crHost; char *crPort; } For a Visual Basic program, the VanConnRecord structure contains the same four items: Type VanConnRecord crName As String crPassword As String crHost As String crPort As String End Type where:
VanConnRecordThe
name of the VanConnRecord structure.
crNameThe
users login name.
crPasswordThe users password. This value is required only
if the user has a password.

crHostThe crPortThe
host name to log on to. port number to use.
)-
The following program code starts a connection to a Vantive server for a user named minotaur. The VanConnRecord structure, which contains the information needed to open the connection, is passed to the VanOpenConnection( )function through the second argument. Later, the VanCloseConnection( )function closes the connection.
3-9
short conn; struct VanConnRecord cr; /* Other program code... */ cr.crName = minotaur; cr.crPassword = labyrinth; cr.crHost = legend; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ } /* Other program code... */ if (VanCloseConnection(conn, 1L, (long *)0) < 0) { /* Success code... */ }
,
#.
Many Vantive API functions use an item known as a bind variable. A bind variable contains information (input) needed by a function, or receives a value (output) generated by the function. Examples of Vantive API functions that use bind variables are:
VanSetField( ),
which changes the contents of a
form field
VanGetField( ), which copies the contents of a form
field to a variable
VanFieldDesc( ), which gets selected information on
a form field. You use the VanData structure to manage the input and output values used by these functions. In a C/C++ program, the VanData structure contains three items:
3-10
struct VanData { short vdType; short vdLength; char *vdPtr; }
In a Visual Basic program, the VanData structure contains two items:

Type VanData vdType As Integer vdPtr As String End Type
where:
VanData
The name of the VanData structure. The type of information generated or retrieved by the function. This information is stored in the bind variable, which is pointed to by the vdPtr element. Specify one of the bind variable types (described below) for this item. The length of the bind variable which is pointed to by vdPtr. When you execute VanGetField( ), vdLength must contain the maximum length for the vdPtr value, includ-
vdType
vdLength
3-11
ing space for the null-terminator. For VanSetField( ), you can specify -1 to denote a null-terminated input string. If the VanGetField( ) or VanFieldDesc( ) function returns the VAN_ETRUNC error, the vdLength value is automatically given the required length.
vdPtr
A pointer to the bind variable. For the

VanSetField( )
function, the bind variable contains data for insertion into a form field. For the VanGetField( ) function, the bind variable contains data retrieved from a form field. For the
VanFieldDesc( )function, the bind
variable is an item of information about a form field.
3-12
)-
The following program code uses the VanSetField( to insert the character string This is an example into a form field named swNote:
)function
struct VanData d; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = This is an example; d.vdLength = -1; VanSetField(form, swNote, &d, &errInfo)
$# #)'
Vantive API includes two functions that change information in a table or a form field:
VanSaveRecord( ),
which saves the record that currently resides in a form field
VanSetField( ),which changes the contents of a form
When an error condition occurs during execution, these functions use the VanSFInfo structure to record the numeric code of the error and the column path in which the error occurred. In a C/C++ program, the VanSFInfo structure contains two items:
struct VanSFInfo { short vsECode; char vsColumnPath[256]; }
In a Visual Basic program, the VanSFInfo structure contains the same two items:
Type VanSFInfo
3-13
vsECode As Integer vsColumnPath As String*255 End Type
where:
VanSFInfo
The name of the VanSFInfo structure. An integer identifying the error condition. See , Page for possible error codes. A buffer that receives the column path of the form field or the table column in which the error occurred.
vsECode
vsColumnPath
)-
The following program code inserts a value into a field named swNote. If an error condition occurs, the program prints out the error code and the column path from the VanSFInfo structure.
struct VanSFInfo errInfo; /* Other program code... */ if (VanSetField(form, swNote, &d, &errInfo) < 0) { printf(%d\n, errInfo.vsECode); printf(%s\n, errInfo.vsColumnPath); /* Other error code... */ }
3-14
$# # % '

Vantive API includes the VanAddActionReceiver( )function, which adds the name of a user or a user group to the receiver list of an Action Request. This function uses the VanActRcv structure, which contains information on the Action Request and the receiver of the request. In a C/C++ program, the VanActRcv structure contains four items:
struct VanActRcv { short vaRType; short vaIsCC; short vaLength; char * vaReceiver; }
In a Visual Basic program, the VanActRcv structure contains three items:

Type VanActRcv vaRType As Integer vaIsCC As Integer vaReceiver As String End Type
where:
VanActRcv
The name of the VanActRcv structure. The type of action receiver. See Action Receiver Types below for possible values. A flag that determines if the Action Request is included in a CC list.
vaRType
vaIsCC
3-15
vaLength
The length of the recipient name you specify with vaReceiver. Specify -1 if the string is null-terminated. The name of the recipient.
vaReceiver
)-
The following program code uses the VanPrepareAction( )and VanAddActionReceiver( )functions to create a new Action Request and add a recipient named HumanResrc to the recipient list:
long action; struct VanActRcv r; /* Other program code... */ action = VanPrepareAction(form, VAN_ASEND); r.vaRType = VAN_RINBOX; r.vaLength = -1; r.vaIsCC = 0; r.vaReceiver = HumanResrc; VanAddActionReceiver (action, &r);
$# #)-
The following program opens a connection to a Vantive server host and port. It then opens the main form for a record type, and gets the external document identification value.
long conn; char docId[30]; long form; long status; struct VanConnRecord cr; struct VanData data;
3-16
cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(ralist, &data)) < 0) { /* Failure code... */ }; if ((status = VanOpenExtDocument(conn, docId, 1L)) < 0) { /* Failure code... */ };
,
#
Vantive API includes several categories of predefined data types. Some types apply to output values generated by the API functions, and some apply to input values used as arguments when you call the functions.
3-17
.
Many of the Vantive API functions that affect forms and Action Requests use a value known as a bind variable. A bind variable contains information (input) needed by a function, or receives a value (output) generated by the function. Bind variables are used by several Vantive API functions, such as VanGetField( ), VanSetField( ), and VanSetActionProperty( ). The vdPtr element of the Vantive API structure VanData points to bind variables. For example, the following program code uses a character buffer array named subject as a bind variable that receives a value extracted from a form field:
struct VanData d; char subject[50]; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = subject; d.vdLength = sizeof(subject); VanGetField(form, swSubject, &d);
Here is a Visual Basic example:

Dim d as VanData Dim Subject as String d.vdType = VAN_TCHAR d.vdPtr = String(255, 0) VanGetField(form, swSubject, d) Subject = d.vdPtr
Since the retrieved value is a character string, the program designates the bind variable type as VAN_TCHAR.

VAN_TCHAR VAN_TSHORT
0 1
Variable to be character string Variable to be short integer (2 bytes)
3-18
VAN_TUSHORT VAN_TINT VAN_TUINT VAN_TLONG VAN_TULONG VAN_TFLOAT VAN_TDOUBLE VAN_TNULL
2 3 4 5 6 7 8 9
Variable to be unsigned short integer (2 bytes) Variable to be integer (machinedependent) Variable to be unsigned integer (machine-dependent) Variable to be long integer Variable to be unsigned long integer (4 bytes) Variable to be single-precision float Variable to be double-precision float
Variable to be ignored, and field to be set to NULL VAN_TCHAR and VAN_TNULL are the only bind variable types allowed for Visual Basic programs. The VAN_TCHAR type denotes null-terminated character strings for C/C++, and denotes Basic String type (which is not null-terminated) for Visual Basic. VAN_TNULL is not a valid output type.
% &

The Vantive API function VanPrepareAction( )starts a new Action Request and, in conjunction with VanAddActionReceiver( )and VanSetActionProperty( ),makes the request ready for execution. The kind of Action Request you create with VanPrepareAction( ) depends on the Action Request type you specify with the functions second argument.

VAN_ASEND VAN_AFORWARD
0 1
Send action Forward action
3-19
VAN_AMARKDONE
Mark action as done
VAN_ACANCEL 3 Mark action as cancelled In the following example, the VanPrepareAction( ) function creates a new Action Request of the Send type by specifying VAN_ASEND for the second parameter: action = VanPrepareAction(form, VAN_ASEND)
%
After you create an Action Request with the VanPrepareAction( )function, you can add recipients to the recipient list of the request with the VanAddActionReceiver( )function. Use either of the following values as the second parameter for the VanAddActionReceiver( ) function to specify whether the Action Request is sent via email or inbox.

VAN_REMAIL
Send an email action
VAN_RINBOX 1 Create an inbox action In the following example, the VanAddActionReceiver( ) function adds an email user to the receiver list for an Action Request. The program sets the vaRType element of the VanActRcv structure to VAN_REMAIL, which specifies an email destination.
long action; struct VanActRcv r; /* Other program code... */ r.vaRType = VAN_REMAIL; r.vaLength = -1; r.vaIsCC = 0; r.vaReceiver = Accounting;
3-20
VanAddActionReceiver (action, &r) < 0);

After you create an Action Request with the VanPrepareAction( )function, you can modify the properties of the Action Request with the VanSetActionProperty( )function. Use any of the following values as the second parameter for the VanSetActionProperty( ) function to specify which modification to make.

VAN_PINBACT VAN_PPRIORITY VAN_PRECEIPT VAN_PACTREQ VAN_PNOTE
0 1 2 3
Specify Inbox action type. Set priority value. Optional. Set the receipt requested flag. Optional. Set the action required flag. Optional.
4 Specify note string. In the following example, the VanSetActionProperty( ) function specifies that the action type of an Action Request is inbox. long action; long VanData d; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = Make Request; d.vdLength = -1; VanSetActionProperty(action, VAN_PINBACT, &d); Here is an example in Visual Basic:
3-21
d.vdType = VAN_TCHAR d.vdPtr = Make Request VanSetActionProperty(action, VAN_PINBACT, d)

'
You can use the VanGetLibInfo( )function to get version information from individual components of the Vantive system. Use any of the following values as the parameter for the VanGetLibInfo( ) function to specify which information to get.

VAN_ICLIENT VAN_ISERVER VAN_IDB VAN_IVERSION VAN_IFDBNAME
0 1 2 3 4
To request Vantive client library version. To request Vantive server version. To request Vantive database dictionary version. To request the currently supported software versions of Vantive API. To request database name.
"

When you open a form and populate it with data from a database, you can use the VanFieldDesc( )function to get information from individual fields in the form. Use any of the following values as the third parameter for the VanFieldDesc( ) function to specify which information to get.

VAN_FNAME VAN_FLABEL
0 1
Fields column path. Return the fields label.
3-22
VAN_FNEWEDIT VAN_FUPEDIT VAN_FDEFAULT VAN_FRAEXTR VAN_FREQUIRED VAN_FDISPCLASS VAN_FTYPE
2 3 4 5 6 7 8
Is field editable for a new record? Is field editable for an existing record? Return the fields default value or the statement to derive the default value. Is the field used for extraction by the Research Agent? Does the field require data? Return the fields display class. Return the fields data type (see Field Type section below).
VAN_FLENGTH 9 Return the fields actual data length. In the following example, the VanFieldDesc( )function retrieves the length of a form field. struct VanData d; long flength; /* Other program code... */ d.vdType = VAN_TINT; d.vdPtr = (char *)&flength; VanFieldDesc(form, 1L, VAN_FLENGTH, &d); Here is a Visual Basic example: Dim d as VanData Dim Flength as Integer d.vdType = VAN_TCHAR d.vdPtr = String(255, 0) VanFieldDesc(form, 1, VAN_FLENGTH, d) Flength = Int(d.vdPtr)
3-23
The field description type specified for the third function argument (VAN_FLENGTH) specifies that the value to be retrieved is field length.
"
The VanFieldDesc( )function retrieves an item of information concerning a form field. The kind of information retrieved depends on the field description type you specify for the third argument of the function. When you specify VAN_FTYPE for the third argument, the form fields data type is returned. This returned value, which is pointed to the vdPtr element of the VanData structure, consists of any of the following field type values.

VAN_FTNUMERIC VAN_FTSTRING VAN_FTEXT VAN_FTDATE VAN_FTDATETIME VAN_FTMONEY
0 1 2 3 4 5
This is a numeric field. This is a string field. This is a large text field. This is a date field. This is a datetime field. This is a money field.
VAN_FTSWID 6 This is a SWID field. In the following example, the VanFieldDesc( )function obtains the data type of a form field. The data type is stored in the integer variable xtype. long xtype; struct VanData d; d.vdType = VAN_TINT; d.vdPtr = (char *)&xtype; VanFieldDesc(form, 1L, VAN_FTYPE, &d);
3-24
if (xtype != VAN_FTSTRING) fprintf(%s, Not a string value.); Note that, since the values contained in the field type variables are integer, the vdType was set to VAN_TINT.
'

When a form has one or more subforms, you can use the VanChildDesc( )function to get the name or the label of the subform. Use either of the following subform description values to determine which value VanChildDesc( ) returns.

VAN_CNAME
Retrieve the subform name (can be used with VanCreateSubForm( )).
VAN_CLABEL 1 Retrieve the subform label. In the following example, the VanChildDesc( ) function retrieves the label of a subform. char label[50]; d.vdType = VAN_TCHAR; d.vdLength = 50; d.vdPtr = label; VanChildDesc(form, 1L, VAN_CLABEL, &d)
-'
When you need a list of currently available inboxes and action receivers, you can use the VanGetInfoList( )function to create an info list. You can then use the VanGetInfoItem( )function to retrieve individual items
3-25
from the list. VanGetInfoList( ) uses its InfoFlag and DetailFlag arguments to determine what kind of list to create. Following are the possible values for the InfoFlag argument of VanGetInfoList( ):

VAN_GINBOX
Retrieve list of inboxes accessible by the user.
VAN_GRECEIVER 1 Retrieve list of action receivers. When InfoFlag value is VAN_GINBOX, the possible values for the DetailFlag argument are:

VAN_GDALL VAN_GDDEFAULT
0 1
Retrieve all values. Retrieve default value only.
When InfoFlag value is VAN_GRECEIVER, the possible values for the DetailFlag argument are:

VAN_REMAIL VAN_RINBOX
0 1
Email name list. Receiver inbox list.
3-26
)
/0
When you alter the contents of a table or a form field with the VanSaveRecord( )or VanSetField( )function, the vsECode element of the Vantive API structure VanSFInfo receives any of the following error codes.
3-27

VAN_SFPRIMARY VAN_SFSECONDARY
0 1
Primary search groups failure. Primary search group completes successfully, but a subsequent search group failed. Data derivation failed.
VAN_SFDERIVE
VAN_SFINCOMPLETE 3 Data is incomplete. The following program code executes the VanSetField( )function. If an error condition occurs, the program checks to see if the error occurred due to a primary search group failure. If this is the cause, the program prints a diagnostic message.
long form; struct VanSFInfo errInfo; /* Other program code... */ if (VanSetField(form, swNote, &d, &errInfo) < 0) { if (errInfo.vsECode == VAN_SFPRIMARY) printf(%s\n%s, Primary, errInfo.vsColumnPath); /* Other error code... */ }
) #
The following is a list of error codes returned by Vantive API functions. Their integer values are defined in the include file vanapi.h. All error codes have negative values.

VAN_EACTION
Action execution error.
3-28
VAN_EACTTYPE VAN_EARG VAN_ECHANGED VAN_ECLOSE VAN_ECURSOR VAN_EDEFAULT VAN_EDESCTYPE VAN_EDOCTIMEOUT VAN_EEMPTY VAN_EFETCH VAN_EFIELD VAN_EFORM VAN_EHANDLE VAN_ELOGIN VAN_EMAXACT VAN_EMAXCONN VAN_EMAXDOC VAN_EMAXFORM VAN_EMAXINFO VAN_EMAXINT VAN_EMEMORY VAN_ENEWREC VAN_ENOTGRP VAN_ENOTOWNER VAN_EOPEN VAN_EOPENDOC
Invalid action type. Invalid function argument. Form data has been modified, but unsaved. Error found while closing form. Cursor not open. Unable to initialize the new record, to set default values. Invalid field description type. Unable to retrieve the entire document despite retries. Form is empty. Data fetch error. Column path or field does not exist in form. Unable to open form. Invalid handle value. Login error. Maximum number of actions exceeded. Maximum number of connections exceeded. Maximum number of document handles exceeded. Maximum number of forms exceeded. Maximum number of info handles exceeded. Integer value exceeded maximum. Out of memory. The record does not yet exist in the database. Field does not belong to search group. Record is not owned by this site. Unable to open cursor. Unable to open specified document.
3-29
VAN_EPERM VAN_ERASRCH VAN_EREADONLY VAN_ESAVE VAN_ESGMANY VAN_ESGNONE VAN_ETIMEOUT VAN_ETOOLONG VAN_ETRUNC VAN_ETYPE VAN_EUPDATE VAN_EVALUE VAN_EVERSION
Field modification permission error. Research Agent search fails. Record is read-only. Record save error. Group search yields too many possible values. Further qualification is required. Group search yields no data. RPC Timeout error. Variable data is too long for form field. Target variable is too small (or short) to contain value from field. Value is truncated. Invalid data type. Problem with entering update mode. Value and target field/variable are incompatible. Software version is invalid.
VAN_EUNKNOWN Internal error. The following is a list of warning codes returned by Vantive API functions. All warnings have positive values.

VAN_WNODATA
Search returns no data.
VAN_WNOSAVE Record is not saved. When no error is found, the return value is:

VAN_NOERROR
No error generated.
3-30
1
"

Vantive API functions are the active language elements you use in an external application to interact with a Vantive server. Use these functions to establish a connection with the server to access documents, to create and manipulate forms and the data they contain, and to create, modify, and execute Action Requests.
% 23

Use the VanAddActionReceiver( ) function to add a recipient name to the list of recipients for an Action Request. Before executing VanAddActionReceiver( ), you must use the VanPrepareAction( )function to create an Action Request and a handle to identify it. Use this handle as the ActionHandle argument for VanAddActionReceiver(). After you create an Action Request and add all necessary receiver names to the recipient list, you can execute the Action Request with the VanDoAction( )function.
The VanAddActionReceiver( ) function uses the following syntax:

4-1
Function Descriptions

long VanAddActionReceiver(long ActionHandle, struct VanActRcv *ActRcv)
9 ;
VanAddActionReceiver
The name of the VanAddActionReceiver(

) function.
ActionHandle
An identifier for the Action Request. Use the VanPrepareAction( ) function to create this handle. A pointer to the action recipient structure VanActRcv, which contains information on the Action Request and the recipient.
ActRcv
%
The VanAddActionReceiver( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE

Invalid action handle or a handle of the wrong type. Out of memory. Illegal Send Action type. The value must be either VAN_RINBOX or VAN_REMAIL. Action Receiver structure is NULL. The receiver name is invalid (that is, it does not exist in the list of Inbox or email names).
VAN_EMEMORY VAN_ETYPE
VAN_EARG VAN_EVALUE
4-2

)-
The following program code uses the VanPrepareAction( ) function to create an Action Request, then uses the VanAddActionReceiver( ) function to add a recipient group named TechSupport to the recipient list of the Action Request. long form; long action; struct VanActRcv r; /* Other program code... */ action = VanPrepareAction(form, VAN_ASEND); r.vaRType = VAN_RINBOX; r.vaLength = -1; r.vaIsCC = 0; r.vaReceiver = TechSupport; if (VanAddActionReceiver (action, &r) < 0) { /* Failure code... */ };

VanDoAction( ), VanPrepareAction( ), VanSetActionProperty( )
4 ' 23

Use the VanAddQualifier( ) function to add a field qualification for use by a search operation. (See VanOpenCursor( ) function in this chapter.) This function provides a form-oriented way of adding search qualifications. You need to use this function before a VanOpenCursor( ) call.
4-3

If you use VanAddQualifier( ) on a form containing an unsaved, modified record, you get the VAN_ECHANGED error. The column path used by VanAddQualifier( ) should identify a valid form field. Otherwise, the function returns the VAN_EFIELD error. The operator used in a VanAddQualifier( ) call must be appropriate for the column path. Otherwise, the function returns the VAN_EVALUE error. The data used for qualification values must also match the column path type. You can make more than one VanAddQualifier( ) call before the VanOpenCursor( ) call. The function puts the qualifications together by an AND operation. In other words, the results need to satisfy all qualifications. The where clause in the VanOpenCursor( ) call also counts as one qualification.
The VanAddQualifier( ) function uses the following syntax:
long VanAddQualifier(long FormHandle, char *ColumnPath, char *Operator, struct VanData *Data)
9 ;
VanAddQualifier
The name of the VanAddQualifier ( ) function. The form handle value returned by the VanCreateMainForm( ) function, VanCreateSubForm( ) function, or the VanCreateInboxForm( ) function. The column path of the form field to apply the qualification.
FormHandle
ColumnPath
4-4

Operator Data
The operator to use for qualification. The value to use for qualification.
%
The VanAddQualifier( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EOPEN VAN_EMEMORY VAN_ECHANGED

Invalid form handle. Invalid form handle. Out of memory. Form contains an unsaved modified record. Invalid data type. Invalid column path. Invalid operator or data value. Parent form is empty.
VAN_ETYPE VAN_EFIELD VAN_EVALUE VAN_EEMPTY
)-
The following program code uses the VanCreateMainForm( ) function to create a main form for case records, then uses VanAddQualifier( ) to add field qualifications for a search. Finally it uses VanOpenCursor( ) to open a cursor on the Vantive server and prepare it for subsequent fetch operations.
4-5

long form; long conn; long status; struct VanData d; ... form = VanCreateMainForm(conn, CASE); ... d.vdType = VAN_TCHAR; d.vdLength = -1; d.vdPtr = Lern%; if (VanAddQualifier(form, swLastName, like, &d) < 0) { /* failure */ ... } d.vdType = VAN_TCHAR; d.vdLength = -1; d.vdPtr = Michael; status = VanAddQualifier(form, swFirstName, =, &d); r.vaRType = VAN_RINBOX; ... status = VanOpenCursor(form, (char *)0, (char *)0);

VanCreateInboxForm( ), VanCreateMainForm( ), VanCreateSubForm( ), VanOpenCursor( )

23
Use the VanChildDesc( ) function to obtain information about a subform of a main form. Each subform has an index number that identifies it. When more than one subform exists, the lowest index number is 1, and you can use the VanNumChilds( )
4-6

function to return the highest index number. All index numbers between 1 and the value returned by VanNumChilds( )are contiguous. You can use the VanNumChilds( ) function in combination with VanChildDesc( ) to evaluate or locate one or more subforms. For example, you can locate a particular subform with a loop command that counts through the possible index numbers, evaluating each subform with the VanChildDesc( ) function.
The VanChildDesc( ) function uses the following syntax:

long VanChildDesc(long FormHandle, long ChildNumber, long ChildDescItem, struct VanData *Data)
9 ;
VanChildDesc FormHandle
The name of the VanChildDesc( ) function. An identifier for the main form. FormHandle must identify the main form; otherwise, you get an error condition. The subform index, a positive whole number that identifies each subform. The range for this number is between 1 and the total number of subforms, which you obtain with the VanNumChilds( ) function. The subform information to request. You must specify VAN_CNAME (to get the name of the subform) or VAN_CLABEL (to get the label of the subform) or VAN_CDISPCLASS (to get the display class of the subform). A pointer to the structure VanData, which receives information on the subform when you execute the VanChildDesc( ) function.
ChildNumber
ChildDescItem
Data
4-7

%
The VanChildDesc( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EMEMORY VAN_EFIELD VAN_EARG VAN_ETRUNC

Invalid form handle. Out of memory.
ChildNumber
is out of range. is invalid.
ChildDescItem
Result data is too long to fit in the bind variable.
)-
The following program code uses VanNumChilds( ) and VanChildDesc( ) in a while loop to list out the names of all subforms of the main form.
long i; long form; long maxchild; struct VanData d; char name[50]; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdLength = 50; d.vdPtr = name; maxchild = VanNumChilds(form); for (i = 0; i < maxchild; i++) if (VanChildDesc(form, i+, VAN_CNAME, &d) < 0) { /* Error code... */ };
4-8

else printf(%s\n, name);

VanNumChilds( )

23
Use the VanCloseConnection( ) function to close a connection to a Vantive server host and port. Closing a connection automatically closes all forms opened for that connection, including inboxes. You open a connection to a Vantive server with the which returns a handle that identifies the connection. Use this handle as the ConnectionHandle argument of the VanCloseConnection( ) function when you close the connection.
VanOpenConnection( )function,
The VanCloseConnection( ) function uses the following syntax:

long VanCloseConnection(long ConnectionHandle, long AbortIfChanged, long *ModFormHandle)
9 ;
VanCloseConnection
The name of the VanCloseConnection( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function.
ConnectionHandle
4-9

AbortIfChanged
A value that determines if a connection is to be closed regardless of whether any changed data in the associated forms are saved. If you set the value of AbortIfChanged to zero, the connection is always closed; otherwise, if data remain unsaved, VanCloseConnection( ) returns VAN_ECHANGED, leaving the connection open. An output variable that automatically receives the handle value of the first form encountered containing modified, unsaved data. Use this handle later to identify, evaluate, and manipulate the form and its contents. To specify no form handle, set the argument to 0.
ModFormHandle
%
The VanCloseConnection( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_ECHANGED

Invalid connection handle. A form with modified, unsaved data was found, and the AbortIfChanged argument was set to a nonzero value.
)-
The following program code uses VanOpenConnection( ) to open a connection to a Vantive server host and port. At a later time, the VanCloseConnection( ) function closes the connection.
long conn; long xform; struct VanConnRecord cr;
4-10

cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = spain; cr.crPort = 1619; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if (VanCloseConnection(conn, 1L, (long *)0) == 0) { /* Success code... */ };


23
Use the VanCloseCursor( ) function to close an open cursor associated with a form. You open a cursor for a form with the VanOpenCursor( When VanCloseCursor( ) executes successfully, the form no longer holds a cursor. If the record contained in the form was changed before VanCloseCursor( ) was called, the record still retains the record and the changes made. If the record was not modified before VanCloseCursor( ) was called, the form and all its subforms are emptied automatically.
)function.
If any child records of a main forms record are modified and unsaved when VanCloseCursor( ) executes, the cursor does not close and the function returns VAN_ECHANGED.
4-11

The VanCloseCursor( ) function uses the following syntax:
long VanCloseCursor(long FormHandle)
9 ;
VanCloseCursor FormHandle
The name of the VanCloseCursor( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
%
The VanCloseCursor( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_ECURSOR VAN_ECHANGED

Invalid form handle. Cursor is not open. There is a modified record in either the form or a subform. RPC timeout. Server operations did not return on time.
VAN_ETIMEOUT
)-
The following program code uses the VanCreateMainForm( )and VanOpenCursor( ) functions to create a main form and open a cursor for the form. At a later time, the program uses the VanCloseCursor( ) function to close the cursor.
4-12

!
long conn; long form; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; if (VanOpenCursor(form, swF > 5, (char *)0) == 0) { /* Success code... */ }; /* Other program code... */ if (VanCloseCursor(form) < 0) { /* Failure code... */ };

VanFetchRecord( ), VanOpenCursor( )

)- 23
Use the VanCloseExtDocument( ) function to close the document handle and free up resources held during document retrieval. VanCloseExtDocument( ) frees up resources held by the document on both VanAPI programs and the Vantive server.
The VanCloseExtDocument( ) function uses the following syntax:

long VanCloseExtDocument(long DocumentHandle)
4-13

!
9 ;
VanCloseExtDocument
The name of the VanCloseExtDocument( ) function. A valid document handle established earlier with the VanOpenExtDocument( ) function.
DocumentHandle
%
The VanCloseExtDocument( ) function returns the document handle when it executes successfully; otherwise, it returns any of the following values:

VAN_EMEMORY VAN_EHANDLE

Out of memory. Invalid form handle.
)-
The following program code uses the VanCloseExtDoc( ) function to close the document handle and free up resources held during document retrieval.
long doc; long conn; long form; long status; char docId[30]; struct VanData data; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; ... if ((conn = VanOpenConnection(1L, &cr)) < 0)
4-14

!
{ /* Failure code */ }; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(form, &data)) < 0) { /* Failure code... */ }; if ((status = VanOpenExtDocument(conn, docId, 1L)) < 0) { /* Failure code ... */ } ... if ((status = VanCloseExtDoc(doc)) < 0) { /* Failure code... */ }

VanExtDocLineCount( ), VanExtDocMaxLineLength( ), VanExtDocName( ), VanGetDocId( ), VanExtDocLine( ), VanOpenExtDocument( )

"23
Use the VanCloseForm( ) function to close a currently open form or inbox.
4-15

!
Closing a main form closes all of its subforms automatically. Attempting to access any subforms of a closed main form results in a VAN_EHANDLE error. If any error occurs during an attempt to close a main form or a subform, all subforms that are still open remain open.
The VanCloseForm( ) function uses the following syntax:

long VanCloseForm(long FormHandle, long AbortIfChanged, long *ModFormHandle)
9 ;
VanCloseForm FormHandle
The name of the VanCloseForm( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. A value that determines if the form is always closed regardless of whether any changed data in the form or its subforms are saved. If you set AbortIfChanged to zero, the form and its subforms are always closed; otherwise, if any data remain unsaved, VanCloseForm( ) leaves the forms open and returns VAN_ECHANGED. An output variable that automatically receives the handle value of the first form encountered containing modified, unsaved data. Use this handle later to identify, evaluate, and manipulate the form and its contents. To specify no form handle, set the argument to 0.
AbortIfChanged
ModFormHandle
4-16

!
%
The VanCloseForm( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_ECHANGED

Invalid form handle. Data in the form or any of its subforms have been changed. Error while closing the form. (Consequently, the form remains open.) RPC timeout. Server operations did not return on time.
VAN_ECLOSE
VAN_ETIMEOUT
)-
The following program code uses VanCreateMainForm( ) function to create a form and a form handle that identifies it. Later, the VanCloseForm( ) function closes the form.
long conn; long form; long modifiedForm; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanCloseForm(form, 1L, &modifiedForm) == 0) { /* Success code... */ };
4-17

"!

VanCreateSubForm( ), VanCreateInboxForm( ), VanCreateMainForm( )
+

"23
Use the VanCreateActionHistoryForm( ) to open an action history form associated with a main form. If no form is associated with the given record type (for the group that the user belongs to), VanCreateActionHistoryForm( ) returns the error VAN_EFORM. An open form contains no data initally. Therefore, in order to access individual fields in a newly opened form using VanGetField( ) and VanSetField( ), you must create a new record for the form using VanNewRecord( ) or fetch data into the form with VanOpenCursor( ) and VanFetchRecord( ).
The VanCreateActionHistoryForm( ) function uses the following syntax: VanCreateActionHistoryForm(long Form Handle, char *ScreenFormName)
9 ;
VanCreateActionHistoryForm
The name of the VanCreateActionHistoryForm function. A form handle that is with the
VanCreateActionHistoryForm,
FormHandle
function.
ScreenFormName
The name of the screen form to open.
4-18

"!
%
The VanCreateActionHistoryForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EMEMORY VAN_EMAXFORM VAN_EFORM

Invalid form handle. Out of memory. Maximum number of forms exceeded. Form open error (use the VanGetMsg( ) function to obtain the error messages).
)-
The following program code uses VanOpenConnection( ) function to create a connection to a Vantive server host and port, and uses VanCreateMainForm ( ) to open a form for case records. It then uses VanCreateActionHistoryForm ( ) to create an instance of an action history form named swActionHistoryPu, which is created with Vantive Edit for the current user group. long conn; long form; long ahform;long conn; struct VanConnRecord cr;
4-19

!!
cr.crName =Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ if ( ( form = VanCreateMainForm (conn, CASE) ) < 0 ) { /* Failure code... */ } if ( (ahform = VanCreateActionHistoryForm(form, swActionHistoryPu) ) < 0) { /* Failure code... */ }

VanCloseClosure( ), VanCloseForm( ), VanFetchRecord( ), VanOpenCursor( ).
"23

Use the VanCreateAtachmentForm( ) to open an action history form associated with a main form.
4-20

!!
If no form is associated with the given record type (for the group that the user belongs to), VanCreateAttachmentForm( ) returns the error VAN_EFORM. An open form contains no data initally. Therefore, in order to access individual fields in a newly opened form using VanGetField( ) and VanSetField( ), you must create a new record for the form using VanNewRecord( ) or fetch data into the form with VanOpenCursor( ) and VanFetchRecord( ).
The VanCreateAttachmentForm( ) function uses the following syntax: VanCreateAttachmentForm(long Form Handle, char *ScreenFormName)
9 ;
VanCreateAttachmentForm
The name of the VanCreateAttachmentForm function. A form handle that is with the VanCreateMainForm, function. The name of the screen form to open.
FormHandle
ScreenFormName
4-21

!!
%
The VanCreateAttachmentForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


)-
The following program code uses VanOpenConnection( ) function to create a connection to a Vantive server host and port, and uses VanCreateMainForm ( ) to open a form for case records. It then uses VanCreateActionHistoryForm ( ) to create an instance of an action history form named swActionHistoryPu, which is created with Vantive Edit for the current user group. long conn; long form; long ahform;long conn; struct VanConnRecord cr; cr.crName =Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000;
4-22

!
if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ if ( ( form = VanCreateMainForm (conn, CASE) ) < 0 ) { /* Failure code... */ } if ( (ahform = VanCreateAttachmentForm(form, swAttachmentPu) ) < 0) { /* Failure code... */ }

"23
Use the VanCreateChildDetailForm( ) to open an action history form associated with a main form. If no form is associated with the given record type (for the group that the user belongs to), VanCreateChildDetailForm( ) returns the error VAN_EFORM. An open form contains no data initally. Therefore, in order to access individual fields in a newly opened form using VanGetField( ) and VanSetField( ),
4-23

!
you must create a new record for the form using VanNewRecord( ) or fetch data into the form with VanOpenCursor( ) and VanFetchRecord( ).
The VanCreateChildDetailForm( ) function uses the following syntax: VanCreateChildDetailForm(long Form Handle, char *ScreenFormName)
9 ;
VanCreateChildDetailForm
The name of the VanCreateChildDetailForm function. A form handle that is with the
VanCreateActionHistoryForm, function.
FormHandle
ScreenFormName
The name of the screen form name which is associated with this child detailform, or the screen name of the child detail form.
%
The VanCreateChildDetailForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


4-24

!
)-
The following program code uses VanOpenConnection( ) function to create a connection to a Vantive server host and port, and uses VanCreateMainForm ( ) to open a form for case records. It then uses VanCreateChildDetailForm ( ) to create an instance of an action history form named swCommentSummaryPu, which is created with Vantive Edit for the current user group. long conn; long form; long ahform;long conn; struct VanConnRecord cr; cr.crName =Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ if ( ( form = VanCreateMainForm (conn, CASE) ) < 0 ) { /* Failure code... */ } if ( (cform = VanCreateChildDetailForm(form, swCommentSummaryPu) ) < 0)
4-25

# !
{ /* Failure code... */ }

-"23
Use the VanCreateInboxForm( ) function to open the inbox for the current user and prepare it for subsequent data access. You can create, manipulate, and execute inbox actions with the VanAddActionReceiver( ), VanPrepareAction( ), VanSetActionProperty( ), and VanDoAction( ) functions. However, an inbox opened by VanCreateInboxForm( ) is a read-only form. For example, any attempt to create a new inbox record with VanNewRecord( ) or to directly modify any inbox records results in the error VAN_EHANDLE. If the inbox name is not associated with the current user name, VanCreateInboxForm( ) returns the error VAN_EFORM.
The VanCreateInboxForm( ) function uses the following syntax:

long VanCreateInboxForm(long ConnectionHandle, char *InboxName)
4-26

# !
9 ;
VanCreateInboxForm
The name of the VanCreateInboxForm( ) function. A connection handle that was established earlier with the VanOpenConnection( ) function. The name of an inbox which is accessible by the current user.
ConnectionHandle
InboxName
%
The VanCreateInboxForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


Invalid connection handle. Out of memory. Maximum number of forms exceeded. Form open error. (Use the VanGetMsg( ) function to obtain the error message.) Invalid inbox name (NULL or empty). RPC timeout. Server operations did not return on time.
VAN_EARG VAN_ETIMEOUT
)-
The following program code uses VanOpenConnection( ) to create a connection to a Vantive server, then uses VanCreateInboxForm( ) to open the inbox named MInb.
4-27

$
!
long conn; long inbox; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((inbox = VanCreateInboxForm(conn, MInb)) < 0) { /* Failure code */ };

VanCreateMainForm( ), VanCreateSubForm( ), VanPrepareAction( )
$ "23
Use the VanCreateMainForm( ) function to open the main form for a record type such as case, resolution, or customer. An open form initially contains no data. Therefore, in order to access individual fields in a newly opened form with VanGetField( )and VanSetField( ),you must create a new record for the form with VanNewRecord( )or fetch data into the form with VanOpenCursor( )or VanFetchRecord( ). If no form is associated with the given record type for the group that the user belongs to, VanCreateMainForm( ) returns VAN_EFORM.
4-28

$
!
The VanCreateMainForm( ) function uses the following syntax:

VanCreateMainForm(long ConnectionHandle, char *ObjectType)
9 ;
VanCreateMainForm ConnectionHandle
The name of the VanCreateMainForm( ) function. An connection handle that was established earlier with the VanOpenConnection( ) function. The type of object to create the main form for.
ObjectType
%
The VanCreateMainForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


Invalid connection handle. Out of memory. Maximum number of forms exceeded. Form open error. (Use the VanGetMsg( ) function to obtain the error message.) Invalid inbox name (NULL or empty).
VAN_EARG
4-29

%
)-
The following program code uses VanOpenConnection( ) to create a connection to a Vantive server host and port, then uses VanCreateMainForm( ) to open a main form for case records.
long conn; long form; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ };

VanCloseCursor( ), VanCloseForm( ), VanFetchRecord( ), VanOpenCursor( )
%(
23
Use the VanCreateRaList( ) function to create a handle for an object type of a result list. You generate the result list with the VanDoResearch( ) function, which returns the number of object types in the list. Before referencing search results in a result list, your program must use VanCreateRaList( ) to create a handle for the search result of each object type. You
4-30

%
identify the item with an integer value representing its ordinal place in the list. This value must be greater than zero and less than the value returned by the VanDoResearch( ) function. You can treat the handle returned by VanCreateRaList( ) as a form handle. However, you cannot use VanAddQualifier( ) with the form handle. You must use the VanOpenCursor( ) function to define the where clause and the order by clause.
The VanCreateRaList( ) function uses the following syntax:
long VanCreateRaList(long FormHandle, long Position)
9 ;
VanCreateRaList FormHandle
The name of the VanCreateRaList( ) function. The valid form handle, established earlier with the VanCreateMainForm( ) function. The position of the object type to create a form handle for. This value must be larger than 0 and less than or equal to the count value returned by the VanDoResearch( ) function. The value of the Position argument must be between 1 and the number of object types returned by the VanDoResearch( ) function, inclusive.
Position
4-31

%
%
The VanCreateRaList( ) function returns the handle to the Research Agent summary form when it executes successfully; otherwise, it returns any of the following values:

VAN_EMEMORY VAN_EMAXFORM VAN_EHANDLE VAN_EARG

Out of memory. Maximum number of forms exceeded. Invalid form handle. Invalid position value.
)-
The following program code uses VanOpenConnection( ) to create a connection to a Vantive server host and port, then uses VanCreateMainForm( ) to open a main form for Case records. Finally, it uses VanCreateRaList( ) to prepare a handle for the first object type.
long form; long ralist; long conn; long rcount; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */
4-32

#!
if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; if ((rcount = VanDoResearch(form, Implicit Or, system requirements combine)) < 0) { /* Failure code */ } if ((ralist = VanCreateRaList(form, 1L)) < 0) { /* Failure code */ };

VanDoResearch( ), VanGetDocId( ), VanCreateMainForm( )
"23
Use the VanCreateSubForm( ) function to open a subform for an object type. If no form is associated with the given object type for the group that the user belongs to, VanCreateSubForm( ) returns the error value VAN_EFORM. An open form initially contains no data. Therefore, in order to access individual fields in a newly opened form with the VanGetField( )and VanSetField( )functions, you must create a new record for the form with VanNewRecord( )or fetch data into the form with VanOpenCursor( )or VanFetchRecord( ).
4-33

#!
The VanCreateSubForm( ) function uses the following syntax:

long VanCreateSubForm(long MainFormHandle, char *SubFormName)
9 ;
VanCreateSubForm MainFormHandle
The name of the VanCreateSubForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the subform to open.
SubFormName
The SubFormName value is the child summary form. Do not confuse this name with that of the child detail form.
%
The VanCreateSubForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


Invalid main form handle. Out of memory. Maximum number of forms exceeded. Form open error. (Use the VanGetMsg( ) function to obtain the error message.)
4-34

#!

VAN_EARG VAN_ETIMEOUT

Invalid inbox name (NULL or empty). RPC timeout. Server operations did not return on time.
)-
The following program code uses VanOpenConnection( ) to create a connection to a Vantive server host and port, and uses VanCreateMainForm( ) to open a main form for case records. It then uses VanCreateSubForm( ) to create an instance of a subform named sw1Pu, which was created with Vantive Tools for the current user group.
long conn; long mform; long sform; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((mform = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; If ((sform = VanCreateSubForm(mform, sw1Pu)) < 0) { /* Failure code... */ };
4-35

!!
!

VanCloseCursor( ), VanCloseForm( ), VanCreateMainForm( ), VanFetchRecord( ), VanOpenCursor( )
"23

Use the VanCreateSummaryForm( ) to open an action history form associated with a main form. If no form is associated with the given record type (for the group that the user belongs to), VanCreateSummaryForm( ) returns the error VAN_EFORM. An open form contains no data initally. Therefore, in order to access individual fields in a newly opened form using VanGetField( ) and VanSetField( ), you must create a new record for the form using VanNewRecord( ) or fetch data into the form with VanOpenCursor( ) and VanFetchRecord( ).
The VanCreateSummaryForm( ) function uses the following syntax: VanCreateSummaryForm(long Form Handle, char *ScreenFormName)
9 ;
VanCreateSummaryForm
The name of the VanCreateSummaryForm function. A form handle that is with the VanCreateMainForm function. The name of the screen form to open.
FormHandle
ScreenFormName
4-36

!!
!
%
The VanCreateSummaryForm( ) function returns a valid form handle when it executes successfully; otherwise, it returns any of the following values:


)-
The following program code uses VanOpenConnection( ) function to create a connection to a Vantive server host and port, and uses VanCreateMainForm ( ) to open a form for case records. It then uses VanCreateSummaryForm ( ) to create an instance of an action history form named swCommentSummaryPu, which is created with Vantive Edit for the current user group. long conn; long form; long ahform;long conn; struct VanConnRecord cr; cr.crName =Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000;
4-37

if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ if ( ( form = VanCreateMainForm (conn, CASE) ) < 0 ) { /* Failure code... */ } if ( (sform = VanCreateSummaryForm(form, swCommentSummaryPu) ) < 0) { /* Failure code... */ }

% 23

Use VanDeleteRecord( ) function to delete associated with a open form.
The VanDeleteRecord( ) function uses the following syntax: VanDeleteRecord(long FormHandle, char *recId)
4-38

9 ;
VanDeleteRecord
The name of the VanDeleteRecord function. A form handle that is with the VanCreateMainForm, function. The record ID which is used to identify which record you would like to delete from the open form. You can pass in the empty string to identify the current record as the delete record.
FormHandle
RecId
%
The VanDeleteRecord( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EDELETE

Invalid form handle. Cannot delete the record.
)-
The following program code uses VanOpenConnection( ) function to create a connection to a Vantive server host and port, and uses VanCreateMainForm ( ) to create a main and then fetch a record into the form and delete it. long conn; long form; long ahform;long conn; struct VanConnRecord cr;
4-39

cr.crName =Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ if ( ( form = VanCreateMainForm (conn, CASE) ) < 0 ) { /* Failure code... */ } if ( (status = VanOpenCursor(form, swCaseId = 5,) ) < 0) { /* Failure code... */ } if ( (status = VanFetchRecord(form, ) ) == 0) { if ( (status = VanDeleteRecord(form,) ) < 0 ) { /* Failure code... */ }
4-40

VanOpenConnection( ), VanCreateMainForm( ), VanFetchRecord( ), VanOpenCursor( ).
23
Use the VanDoAction( )function to execute an Action Request. Before you can execute the VanDoAction( ) function, you must use the VanPrepareAction( )function to create an Action Request and an action handle to identify it. Use this handle as the ActionHandle argument for VanDoAction( ). When you execute VanDoAction( ), the action handle is freed (that is, it no longer identifies the action). If VanDoAction( ) does not execute successfully, the action handle is maintained so the user can correct the problem causing the error.
long VanDoAction(long ActionHandle)
The VanDoAction( ) function uses the following syntax:
9 ;
VanDoAction ActionHandle
The name of the VanDoAction( ) function. An identifier for the Action Request. Use the VanPrepareAction( ) function to create this handle.
4-41

%
The VanDoAction( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EACTION VAN_ETIMEOUT

Invalid action handle. Error executing action. RPC timeout. Server operations did not return on time.
)-
The following program code uses the VanPrepareAction( ) function to create an Action Request and uses the VanAddActionReceiver( ) function to add a recipient group named TechSupport to the recipient list of the Action Request. It then uses the VanDoAction( ) function to perform the Action Request.
long form; long action; struct VanActRcv r; /* Other program code... */ action = VanPrepareAction(form, VAN_ASEND); r.vaRType = VAN_RINBOX; r.vaLength = -1; r.vaIsCC = 0; r.vaReceiver = TechSupport; if (VanAddActionReceiver (action, &r) < 0) { /* Failure code */ }; /* Other program code... */
4-42

if (VanDoAction(action) < 0) { /* Failure code */ };

VanAddActionReceiver( ), VanPrepareAction( ), VanSetActionProperty( )
%
23
Use the VanDoResearch( )function to perform a Research Agent search operation and return the number of object types found in the result list. The number of outstanding Research Agent searches is limited to 1 (that is, you can execute only one VanDoResearch( ) function call at a time). The search mode for the standard Research Agent can be one of the three values: Implicit Or, Implicit And, and Simple Count. The search mode for non-standard Research Agent (for example, Fulcrum) varies because users might be able to customize the search modes. You can provide search text in place of the form extractable data. If this pointer is either NULL or contains no data (empty string), the system uses the forms extractable data.
The VanDoResearch( ) function uses the following syntax:

long VanDoResearch(long FormHandle, char *Mode, char *Text)
4-43

9 ;
VanDoResearch FormHandle
The name of the VanDoResearch( ) function. Valid form handle established earlier with the VanCreateMainForm( ) function. The search mode. Text to use for the search (may be NULL or empty).
Mode Text
%
The VanDoResearch( ) function returns the number of object types found in the result list when it executes successfully. Otherwise, it returns any of the following values:

VAN_EMEMORY VAN_ERASRCH VAN_EHANDLE

Out of memory. Research Agent search failed. Invalid action handle.
The number of objects found in the result list is always greater than or equal to zero.
)-
The following program code uses the VanOpenConnection( ) to create a connection to a Vantive server host and port, then uses VanCreateMainForm( ) to open a main form for case
4-44

%
records. Finally, it uses VanDoResearch( ) to perform a Research Agent search operation and returns the number of object types found in the result list.
long count; long form; long conn; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ if ((count = VanDoResearch(form, Implicit Or, (char *)0)) < 0) { /* Failure code */ };

VanCreateRaList( ), VanGetDocId( )
)-( 23
Use the VanExtDocLine( ) function to retrieve a text line from the document opened by VanOpenExtDocument( ).
4-45

%
The VanExtDocLine( ) function uses the following syntax:

long VanExtDocLine(long DocHandle, unsigned long LineNumber, struct VanData *Data)
9 ;
VanExtDocLine DocHandle
The name of the VanExtDocLine( ) function. A valid form handle that was established earlier with the VanOpenExtDocument( ) function. The text line number to retrieve. Output location for the retrieved text line. The value of the LineNumber parameter cannot be less than 1 or greater than 2147483646. In Visual Basic, the type of LineNumber can be long. The receiving variable described by Data must be VAN_TCHAR. The VAN_TCHAR variable must have enough space to retrieve the whole line. If you want to get the maximum length of any line in the document, use the VanExtDocMaxLineLength( ) function. Always add 1 to this value to avoid the VAN_ETRUNC error.
LineNumber Data
4-46

%
%
The VanExtDocLine( ) function returns 0 when it executes successfully. Otherwise, it returns any of the following values:

VAN_EMEMORY VAN_ETRUNC VAN_EHANDLE VAN_ETYPE

Out of memory. The text line is too long. Truncation error. Invalid form handle. Receiving variable type is invalid. The type must be VAN_TCHAR. Line number value is too small or too large.
VAN_EARG
)-
The following program code uses the VanOpenExtDocument( ) function to initiate access to an external document from the Research Agent server. It then uses the VanExtDocLine( ) function to retrieve a text line from the document opened by the VanOpenExtDocument( ) function.
long doc; long conn; char docid[80]; char linebuf[80]; struct VanData data; long status; ... doc = VanOpenExtDocument(conn, docid, 1L); data.vdType = VAN_TCHAR; data.vdPtr = linebuf; data.vdLength = sizeof(linebuf); if ((status = VanExtDocLine(doc,
4-47

%
1L, &data)) < 0) { /* failure */ ... }

VanCloseExtDocument( ), VanExtDocLineCount( ), VanExtDocLineMaxLength( ), VanOpenExtDocument( )
)-( 23
Use the VanExtDocLineCount( ) function to return the total number of lines in the retrieved document. The maximum number of lines this function can return is 2147483647. If the document has more than 2147483647 lines, the VanExtDocLineCount( ) function returns 2147483647 as the number of lines.
The VanExtDocLineCount( ) function uses the following syntax:

long VanExtDocLineCount(long DocHandle)
9 ;
VanExtDocLineCount DocHandle
The name of the VanExtDocLineCount( ) function. Valid form handle established earlier with the VanOpenExtDocument( ) function.
4-48

%
%
The VanExtDocLineCount( ) function returns the total number of lines when it executes successfully; otherwise, it returns the following value:

VAN_EHANDLE

Invalid form handle.
)-
The following program code uses the VanOpenExtDocument( ) function to initiate access to an external document from the Research Agent server. It then uses the VanExtDocLineCount( ) function to return the total number of lines in the retrieved document.
long doc; long conn; long form; long docId; long linecount; struct VanData data; struct VanConnRecord cr; ... cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; ... if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */
4-49

%$
%
}; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(form, &data)) < 0) { /* Failure code... */ }; doc = VanOpenExtDocument(conn, docId, 1L); if ((linecount = VanExtDocLineCount(doc)) < 0) { /* failure */ ... }

VanCloseExtDocument( ), VanExtDocLine( ), VanExtDocLineMaxLength( ), VanOpenExtDocument( )
)-( $-( #23

Use the VanExtDocLineMaxLength( ) function to return the maximum length of any line in the retrieved document. The maximum line length this function can return is 2147483647. If the line is longer, the VanExtDocLineMaxLength( ) function returns 2147483647 as the maximum length of the line. Use this value to allocate space for text line retrieval using the VanExtDocLine( ) function. Always add 1 to this length to avoid the error VAN_ETRUNC.
4-50

%$
%
The VanExtDocLineMaxLength( ) function uses the following syntax:

long VanExtDocLineMaxLength(long DocHandle)
9 ;
VanExtDocLineMaxLength
The name of the VanExtDocLineMaxLength( ) function. Valid form handle that is established earlier with the function VanOpenExtDocument( ).
DocHandle
%
The VanExtDocLineMaxLength( ) function returns the maximum length when it executes successfully; otherwise, it returns the following value:

VAN_EHANDLE

)-
The following program code uses the VanOpenExtDocument( ) function to initiate access to an external document from the Research Agent server. It then uses the VanExtDocLineMaxLength( ) function to return the maximum length of any line in the retrieved document.
long doc; long conn; long form; long docId; long linelength; struct VanData data;
4-51

%$
%
struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; ... if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(form, &data)) < 0) { /* Failure code... */ }; ... doc = VanOpenExtDocument(conn, docId, 1L); if ((linelength = VanExtDocLineMaxLength(doc)) < 0) { /* failure */ ... }

VanCloseExtDocument( ), VanExtDocLine( ), VanExtDocLineCount( ), VanOpenExtDocument( )
4-52

&
!
)- 23
Use the VanExtDocName( ) function to retrieve a record from the Vantive server and store it in the form. The type of the receiving variable must be VAN_TCHAR. Do not confuse a document name with a document id. Use a document id to open a document. Use a document name for labelling.
The VanExtDocName ( ) function uses the following syntax:

long VanExtDocName(long DocHandle, struct VanData *Data)
9 ;
VanExtDocName DocHandle
The name of the VanExtDocName( ) function. Valid form handle that is established earlier with the function VanOpenExtDocument( ). A pointer to the structure VanData, which is the receiving variable for document name.
Data
%
The VanExtDocName( ) function returns 0 when it executes successfully; otherwise, it returns the following values:

VAN_EHANDLE

4-53

&
!

VAN_ETYPE VAN_ETRUNC

Invalid receiving data type. Name is too long for receiving variable. Truncation error.
)-
The following program code uses the VanOpenExtDocument( ) function to initiate access to an external document from the Reseach Agent server. It then uses the VanExtDocName( ) function to retrieve the document name as identified by the Research Agent.
long doc; long conn; long status; long docId struct VanData data; char docname[30]; ... if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ } ... if ((docId = VanGetDocId(form, &data)) < 0) { /* Failure code... */ }; ... doc = VanOpenExtDocument(conn, docId, 1L); data.vdType = VAN_TCHAR; data.vdPtr = docname; data.vdLength = sizeof(docname);
4-54

if ((status = VanExtDocName(doc, &data)) < 0) { /* failure */ ... }

VanCloseExtDocument( ), VanOpenExtDocument( )
" % 23

Use the VanFetchRecord( ) function to retrieve a record from the Vantive server and display its data in a form. Before using VanFetchRecord( ), perform the following steps: Establish a connection to a Vantive server host and port using the VanOpenConnection( )function. Open a form and generate a handle value for it using the
VanCreateInboxForm( ), VanCreateMainForm( ),or VanCreateSubForm( )function.
Open a cursor for the form with the VanOpenCursor( ) function, using the handle value as the FormHandle argument. If you skip this step (or close the cursor with the VanCloseCursor( )function), executing VanFetchRecord( )returns the error VAN_ECURSOR. Once you fetch a record with VanFetchRecord( ), you can access its data with the VanGetField( )function or insert a value in one of its fields with the VanSetField( )function.
4-55

Once you execute VanFetchRecord( ) successfully, any subform that contains data related to the previously-active record is emptied and the cursor operating on this subform is closed. Any attempt to use the cursor results in the error VAN_ECURSOR. If the form or any of its subforms contains modified, unsaved data, or if there are pending actions for the form, VanFetchRecord( ) returns the error VAN_ECHANGED.
The VanFetchRecord( ) function uses the following syntax:

long VanFetchRecord(long FormHandle)
9 ;
VanFetchRecord FormHandle
The name of the VanFetchRecord( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
%
The VanFetchRecord( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_WNODATA VAN_EHANDLE

No more data. The fetch is finished. Invalid form handle.
4-56

VAN_EFETCH

Found error(s) during fetch. Use VanGetMsg( ) to retrieve the text message. Cursor is not open. RPC timeout. Server operations did not return on time.
VAN_ECURSOR VAN_ETIMEOUT
)-
The following program code uses the VanCreateMainForm( )and VanOpenCursor( ) functions to create a main form for case records and open a cursor for the form. At a later time, the program uses the VanFetchRecord( ) function in a while loop to go from record to record and evaluate the contents of each. After the loop terminates, an if...else statement uses the last value returned by VanFetchRecord( ) to evaluate the cause of termination.
long conn; long form; if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; if (VanOpenCursor(form, swCaseId > 5) == 0) { /* Success code... */ }; /* Other program code... */ while ((status = VanFetchRecord(form)) == 0) { /* Record Evaluation code... */ };
4-57

if (status == VAN_WNODATA) { /* No-more-data code */ }; else if (status < 0) { /* Failure code... */ };

VanCloseCursor( ), VanGetField( ), VanOpenCursor( ), VanSetField( )
"
23
Use the VanFieldDesc( ) function to get selected information from a field in a form.
The VanFieldDesc( ) function uses the following syntax:

long VanFieldDesc(long FormHandle, long FieldNumber, long DescItem, struct VanData *Data)
9 ;
VanFieldDesc FormHandle
The name of the VanFieldDesc( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. The form field number of the field to evaluate.
FieldNumber
4-58

DescItem Data
The type of information to obtain from the form field. A pointer to the structure VanData, which receives information on the field when you execute the VanFieldDesc( ) function.
%
The VanFieldDesc( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EFIELD

Invalid form handle. The requested form field number is either too large (greater than the number of fields in the form), or invalid (less than or equal to zero). Invalid output variable type. Invalid field description type value. Result data is too long (or too large) to fit in bind variable.
VAN_ETYPE VAN_EARG VAN_ETRUNC
)-
The following program code uses the VanCreateMainForm( ) function to create a form for case records. Later, it uses VanFieldDesc( ) to insert a copy of a fields label into a variable named buffer. If successful, the program prints the label.
long conn; long form; long status; struct VanData d; char buffer[50];
4-59

if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = buffer; d.vdLength = 50; if (VanFieldDesc(form, 1L, VAN_FLABEL, &d) < 0) { /* Error code... */ }; else { printf(%s, buffer); };
When you specify VAN_FTYPE for the DescItem argument, VanFieldDesc( ) generates the form fields data type. The data type is expressed as one of the Vantive API field type values. For example, the following program code gets the form fields data type and prints a message if the type is not numeric.
long buffer; struct VanData d; d.vdType = VAN_TINT; d.vdPtr = buffer; VanFieldDesc(form, 1L, VAN_FTYPE, &d); if (buffer != VAN_FTNUMERIC) fprintf(%d, Not a numeric value.);

VanCreateMainForm( ), VanCreateInboxForm( ), VanCreateSubForm( ), VanNumFields( )
4-60

%
" '(
23
Use the VanFreeInfoList( ) function to free resources held by an info list. After you execute VanFreeInfoList( ), the info list you specify with InfoHandle no longer exists.
The VanFreeInfoList( ) function uses the following syntax:

long VanFreeInfoList(long InfoHandle)
9 ;
VanFreeInfoList InfoHandle
The name of the VanFreeInfoList( ) function. The info list handle that was established earlier with the VanGetInfoList( ) function.
%
The VanFreeInfoList( ) function returns 0 when it executes successfully; otherwise, it returns the following value:

VAN_EHANDLE

Invalid info handle.
)-
The following program code establishes a connection to a Vantive host and port, creating a connection handle named conn. Later, the program code starts an info list (for a list box) with the VanGetInfoList( )function, creating an info list handle named info. Finally, the
4-61

'
program code removes the info list with the VanFreeInfoList( ) function, freeing the resources that the info list used.
long conn; long info; struct VanConnRecord cr; cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = spain; cr.crPort = 1619; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ info = VanGetInfoList(conn, VAN_GINBOX, VAN_GDALL); /* Other program code... */ VanFreeInfoList(info);

VanGetInfoItem( ), VanGetInfoList( ), VanRestartInfoList( )
23

Use the VanGetDocId( ) function to get the external document identification value. You can use this value in subsequent VanOpenExtDocument( ) calls to retrieve the document.
long VanGetDocId(long FormHandle,
The VanGetDocId( ) function uses the following syntax:
4-62

'
struct VanData *Data)
9 ;
VanGetField FormHandle
The name of the VanGetDocId( ) function. An open form handle that was established earlier with the VanCreateRaList( ) function. A pointer to the structure VanData, which receives document identification value upon function return.
Data must point to buffers of type VAN_TCHAR.
Data
%
The VanGetDocId( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EMEMORY VAN_EHANDLE VAN_ETRUNC VAN_ETYPE

Out of memory. Invalid form handle. Truncation error. Invalid output data type.
)-
The following program code uses the VanOpenConnection( ) function to establish a connection to the Vantive server and port. Later, it uses the VanCreateMainForm( )function to open the Main Information form for the object type. The VanGetDocId( )function uses the form handle established by VanCreateMainForm( ) to return the external document identification value.
4-63

'&
long form; long status; long conn; long docId; struct VanData data; struct VanConnRecord cr; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(form, &data)) < 0) { /* Failure code... */ };

VanDoResearch( ), VanGetDocId( )
23

Use the VanGetActionNote( ) function to get the action note for an action history record.
4-64

'&
retrieves the action note for an action history record and put in the bind variable pointed to by the vdPtr element of the VanData structure.
VanGetActionNote( )
If the note is too large to fit in the bind variable, VanGetActionNote( ) returns the error VAN_ETRUNC and the vdLength element is automatically set to the length of the buffer required for successful operation.
The VanGetActionNote( ) function uses the following syntax:

long VanGetDocId(long ActionFormHandle, struct VanData *Data)
9 ;
VanGetActionNote ActionFormHandle
The name of the VanGetActionNote( ) function. An open form handle that was established earlier with the VanCreateActionHistory( ) function. A pointer to the structure VanData, which receives data from the action note when you execute the VanGetActionNote( ) function
Data
%
The VanGetActionNote( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EARG

Invalid form handle. Invalid output data description.
4-65

'&

VAN_EEMPTY VAN_ETYPE VAN_ETRUNC

Form is empty. Invalid output data type. The data is truncated.
)-
The following program code uses the VanOpenConnection( ) function to establish a connection to the Vantive server and port, and uses the VanCreateMainForm( )function to open the Main Information form for case records. It then uses VanCreateActionHistroyForm ( ) to create an instance of an action history form named swActionHistoryPu, which is created with Vantive Edit for the current user group. Finally, it uses VanGetActionNote ( ) to get the note.
long long long char conn; form; aform; buff[1024];
struct VanConnRecord cr; struct VanData data; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE))
4-66

'&
< 0) { /* Failure code */ } if ((aform = VanCreateActionHistoryForm(form, swActionHistoryPu)) < 0) { /* Failure code */ } /* Other program code... */ data.vdType = VAN_TCHAR; data.vdLength = 1024; data.vdPtr = buf; while ( VanFetchRecord (form) == 0) { /* other program code */ } while ( VanFetchRecord (aform) == 0) { /* other program code */ } if (( VanGetActionNote (aform,&data) ) < 0 ) { /* failure code */ }

VanOpenConnection( ), VanCreateMainForm( ), VanCreateActionHistoryForm( )
4-67

'
!
23
VanAPI can get attachment with OLE2 control information as attachment Head and Tail. It is up to the application to do the necessary process of the OLE2 control information inside the attachment file before using the attachement. Use the VanGetAttachment( ) function to get an attachment from an open object to a buffer.
VanGetAttachment( ) retrieves part of or all of the attachment from an open object and puts it in the bind variable, which is pointed to by the vdPtr element of the VanData structure. Whether VanGetAttachment( ) can get a whole attachment file back at once depends upon how large the buffer pointed to by vdPtr is. Every time VanGetAttachment( ) gets the maximum vdLength length of the attachment data back. If the return value of VanGetAttachment( ) is less than the length of vdLength of the VanData structure, the whole attachment file is retrieved back at once. If the return value of the VanGetAttachment( ) is equal to the vdLength, you must call VanGetAttachment( ) again to get the next piece of the attachment. You need to keep calling VanGetAttachment( ) until the return value of the function is less than the length of vdLength.
The VanGetAttachment( ) function uses the following syntax:

long VanGetAttachment(long AttachmentFormHandle, struct VanData *Data)
4-68

'
!
9 ;
VanGetAttachment AttachmentFormHandle
The name of the VanGetAttachment( ) function. An open form handle that was established earlier with the VanCreateAttachmentForm( ) function. A pointer to the structure VanData, which receives data from the action note when you execute the VanGetActionNote( ) function.
Data
%
The VanGetAttachment( ) function returns the length of bytes read in this run when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EARG VAN_EEMPTY VAN_ESTARTBLOB

Invalid form handle. Invalid output data description. Form is empty. The Blob (Binary Large Object) has already started. Get Blob error.
VAN_EGETBLOB
)-
The following program code uses the VanOpenConnection( ) function to establish a connection to the Vantive server and port, and uses the VanCreateMainForm( )function to open the Main Information form for case records. It then uses VanCreateAttachmentForm ( ) to create an instance of an attachment form named swAttachmentPu,
4-69

'
!
which is created with Vantive Edit for the current user group. Finally, it uses VanGetAttachment ( ) to get the attachment back.
struct VanConnRecord cr; struct VanData data; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ } if ((aform = VanCreateAttachmentForm(form,sw AttachmentPu)) < 0) { /* Failure code */ } /* Other program code... */ data.vdType = VAN_TCHAR; data.vdLength = 1024; data.vdPtr = buf; while ( VanFetchRecord (form) == 0) { /* other program code */
4-70

'
}; while ( VanFetchRecord (aform) == 0) { /* other program code */ while ( ((bytesRead == VanGetAttachment (aform, &data) ) == 1024 && bytesRead > 0 ) ) { /* program code which process the attachment data */ if (( bytesRead < 1024 && bytesRead > 0 ) ) { break; } } if ( bytesRead < 0 ) { /* failure code */ };

VanOpenConnection( ), VanCreateMainForm( ), VanCreateAttachmentForm( ), VanFetchRecord( )
23

Use the VanGetDocId( ) function to get the external document identification value. You can use this value in subsequent VanGetExtDocument( ) calls to retrieve the document.
-
4-71

'
long VanGetDocId(long ActionFormHandle, struct VanData *Data)
9 ;
VanGetDocId FormHandle
The name of the VanGetDocId( ) function. An open form handle that was established earlier with the VanCreateRaList( ) function. A pointer to the structure VanData, which receives document identification value upon funtion return. Data must point to buffers of VAN_TCHAR.
Data
%
The VanGetDocId( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EMEMORY VAN_ETYPE VAN_ETRUNC

Invalid form handle. Out of memory. Invalid output data type. The data is truncated.
)-
The following program code uses the VanOpenConnection( ) function to establish a connection to the Vantive server and port, and uses the VanCreateMainForm( )function to open the Main Information form for the object type. The VanGetDocId( ) function uses the form handle established by VanCreateMainForm( ) to return the external document identification value.
4-72

'
struct VanConnRecord cr; struct VanData data; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ } /* Other program code... */ data.vdType = VAN_TCHAR; data.vdLength = 20; data.vdPtr = malloc(20); if (( VanGetDocId (aform,&data) ) < 0 ) { /* failure code */ }

VanOpenConnection( ), VanCreateMainForm( )
4-73

'
" 23

Use the VanGetField( ) function to copy data from a form field to a variable.
VanGetField( )
retrieves data from the field and puts it in the bind variable, which is pointed to by the vdPtr element of the VanData structure.
If the value is too large to fit in the bind variable, VanGetField( ) returns the error VAN_ETRUNC. However, if the value you specify is of type VAN_TCHAR, the vdLength element is automatically set to the length of the buffer required for successful operation. If the value in the field and the bind variable type are incompatible (for example, a negative numeric value in the field and an unsigned integer bind variable), VanGetField( ) returns the error VAN_EVALUE.
long VanGetField(long FormHandle, char ColumnPath, struct VanData *Data)
The VanGetField( ) function uses the following syntax:
9 ;
VanGetField FormHandle
The name of the VanGetField( ) function. An open form handle that was established earlier with the VanCreateRaList( ) function. A path to the column of the field you access with VanGetField( ). A pointer to the structure VanData, which receives data from the field when you execute the VanGetField( ) function.
ColumnPath
Data
4-74

'
%
The VanGetField( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EEMPTY VAN_EPERM VAN_EARG VAN_EFIELD VAN_ETRUNC

Invalid form handle. Form is empty. Field is inaccessible. Invalid output data description. Invalid field name. Fields data is too long (or too large) to fit in the bind variable. It has been truncated to fit the variable. Invalid variable type. Value is not compatible with bind variables type.
VAN_ETYPE VAN_EVALUE
)-
The following program code uses the VanCreateMainForm( )function to create a form for case records. Later, it uses the VanFetchRecord( )function in a while loop to move from record to record in the main table. The VanGetField( )function accesses a field named swSubject in each record, inserts the fields contents into a variable named subject, and prints the contents each time.
long long long char form; conn; status; subject[100];
4-75

'!
unsigned long repid; struct VanData d; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ while (VanFetchRecord(form) == 0) { d.vdType = VAN_TCHAR; d.vdPtr = subject; d.vdLength = sizeof(subject); status = VanGetField(form, swSubject, &d); /* Error checking code... */ printf(%s\n, subject); };

VanCreateMainForm( ), VanCreateInboxForm( ), VanCreateSubForm( )
' 23

Use the VanGetInfoItem( ) function to return a value in an info list for an inbox. The VanGetInfoItem( ) function keeps an internal pointer that accesses a value contained in the info list. The first time you execute VanGetInfoItem( ), the pointer accesses the first value in the list. Each subsequent time you execute VanGetInfoItem( ), the pointer advances to the next value. You can return the pointer the beginning by calling VanRestartInfoList( ).
4-76

'!
VanGetInfoItem( ) retrieves the item and inserts it in the
bind variable, which is pointed to by the vdPtr element of the VanData structure. If the value is too large to fit in the bind variable, VanGetInfoItem( ) returns the error VAN_ETRUNC and the vdLength element is automatically set to the length of the buffer required for successful operation. does not free any resource held by the list. To free the list and its handle, use VanFreeInfoList( ).
VanGetInfoItem( )
The VanGetInfoItem( ) function uses the following syntax:

long VanGetInfoItem(long InfoHandle Handle, struct VanData *Data)
9 ;
VanGetInfoItem InfoHandle
The name of the VanGetInfoItem( ) function. The handle of the info list that was established earlier with the VanGetInfoList( ) function. A pointer to the structure VanData, which receives data from the field when you execute the VanGetInfoItem( ) function.
Data
4-77

'!
%
The VanGetInfoItem( ) function returns 0 when it executes successfully; otherwise, it returns any of the following value:

VAN_EHANDLE VAN_EARG VAN_ETRUNC

Invalid info handle. Invalid output data description. Field's data is too long (or large). It has been truncated to fit variable. Invalid variable type. If there is no more data in the list, VanGetInfoItem( ) may return:
VAN_ETYPE

VAN_WNODATA

No more data in the list.
)-
The following program code establishes a connection to a Vantive host and port, creating a connection handle named conn. Later, the program code starts an info list (for a list box) with the VanGetInfoList( ) function, creating an info list handle named info. The program then uses the VanGetInfoItem( ) function in a while loop to access and evaluate items in the info list.
long conn; long info; struct VanConnRecord cr; struct VanData d; char inboxName[100];
4-78

'%
cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = spain; cr.crPort = 1619; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ info = VanGetInfoList(conn, VAN_GINBOX, VAN_GDALL); while (1) { d.vdType = VAN_TCHAR; d.vdPtr = inboxName; d.vdLength = sizeof(inboxName); status = VanGetInfoItem(info, &d); /* Error checking code... */ if (status == VAN_WNODATA) break; else if (status < 0) /* Other program code... */ }

VanFreeInfoList( ), VanGetInfoList( ), VanRestartInfoList( )
'(

Use the VanGetInfoList( ) function to retrieve a list of inbox-related information. This information may consist of:
4-79

'%

Accessible inbox names Email receiver names Inbox receiver names
VanGetInfoList( ) reads the info list from the Vantive server and stores the list in memory. The function also generates an info list handle to identify the list for other API functions.
Once the list is generated, the first execution of the VanGetInfoItem( ) function returns the first value in the list. Each subsequent execution of VanGetInfoItem( )returns the next item in the list. This function (and others such as VanFreeInfoList( ) and VanRestartInfoList( ))use the info list handle generated by VanGetInfoList( ) to reference the list. If there are more than 8 info lists outstanding, the VAN_MAXINFO error is returned.
The VanGetInfoList( ) function uses the following syntax:

InfoHandle = long VanGetInfoList(long ConnectionHandle, long InfoFlag, long DetailFlag)
9 ;
VanGetInfoList ConnectionHandle
The name of the VanGetInfoList( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function.
4-80

'%
InfoFlag
The type of information to retrieve. Specify VAN_GINBOX for a list of accessible inboxes, or VAN_GRECEIVER for a list of email or inbox receivers. The type of detail information to retrieve. If you specify VAN_GINBOX as the InfoFlag parameter, specify VAN_GDALL or VAN_GDDEFAULT for the DetailFlag parameter. If you specify VAN_GRECEIVER as the InfoFlag parameter, specify VAN_REMAIL or VAN_RINBOX for the DetailFlag parameter. Use the InfoFlag and DetailFlag parameters to specify the type of info list to make with VanGetInfoList( ):
DetailFlag
For a list of accessible inbox names, specify VAN_GINBOX as the InfoFlag parameter. To create a list containing all values, specify VAN_GDALL as the DetailFlag parameter. To create a list containing only the default value, specify VAN_GDDEFAULT as the DetailFlag parameter. For a list of email receiver names, specify VAN_GRECEIVER as the InfoFlag parameter and VAN_REMAIL as the DetailFlag parameter. For a list of inbox receiver names specify VAN_GRECEIVER as the InfoFlag parameter and VAN_RINBOX as the DetailFlag parameter.
4-81

'%
%
The VanGetInfoList( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EARG VAN_EMAXINFO VAN_EMEMORY

Invalid connection handle. Invalid info or detail flag values. Maximum number of info lists exceeded. Out of memory.
)-
The following program code establishes a connection to a Vantive host and port, creating a connection handle named conn. Later, the program code starts an info list (for a list box) with the VanGetInfoList( ) function, creating an info list handle named info.
long conn; long info; struct VanConnRecord cr; struct VanData d; char inboxName[100]; cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = spain; cr.crPort = 1619; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ info = VanGetInfoList(conn,
4-82

'%#
VAN_GINBOX, VAN_GDALL); if (info < 0) { /* Error code... */ }

VanFreeInfoList( ), VanGetInfoItem( ), VanRestartInfoList( )
( '23
Use the VanGetLibInfo( ) function to get the version of the client library, the Vantive server, the Vantive database dictionary, or Vantive API for a specified connection.
The VanGetLibInfo( ) function uses the following syntax:

long VanGetLibInfo(long ConnectionHandle, long InfoField, struct VanData *Data)
9 ;
VanGetLibInfo ConnectionHandle
The name of the VanGetLibInfo( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function. This argument is ignored for client library and Vantive API version requests.
4-83

'%#
InfoField
The version information to get. To identify the client library version, specify VAN_ICLIENT. To identify the Vantive server version, specify VAN_ISERVER. To identify the Vantive database dictionary version, specify VAN_IDB. To identify the database name, specify VAN_IFDBNAME. To identify the Vantive API version, specify VAN_IVERSION. (For the first version of Vantive API, the returned value is 1.) A pointer to the structure VanData, which receives the version string when you execute the VanGetLibInfo( ) function. The vdType element must specify the VAN_TCHAR type.
Data
%
The VanGetLibInfo( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_ETYPE VAN_EARG VAN_ETRUNC

Invalid connection handle.
vdType element of VanData structure has incorrect type. InfoField
argument value is invalid.
The requested version string is too long (or too large) to fit in the bind variable. It has been truncated to fit the variable.
)-
The following program code uses VanGetLibInfo( ) to insert the Vantive server version into a variable named buffer, then prints the value.
4-84

'$
long conn; char buffer[50]; struct VanData d; /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = buffer; d.vdLength = sizeof(buffer); if (VanGetLibInfo(conn, VAN_ISERVER, &d) < 0) { /* Error code... */ }; printf(%s, buffer);

$
#23
Use the VanGetMsg( ) function to retrieve the Vantive server or Vantive API error message (if any) that was generated by the last-executed statement.
VanGetMsg( )
copies the error message into a buffer variable you specify as the Buffer argument. The length of this variable should always include space for the nullterminator character. If the last executed statement ran without error, the value returned through the Buffer argument is empty.
The VanGetMsg( ) function uses the following syntax:

long VanGetMsg(long ConnectionHandle, char *Buffer, long MaxLength)
4-85

'$
9 ;
VanGetMsg ConnectionHandle
The name of the VanGetMsg( ) function. An open server connection handle that was established earlier with the VanOpenConnection( )function. If the VanOpenConnection() function failed, specify -1L. A character buffer that contains the error message. The text in this buffer is null-terminated. The size of the buffer. The error message is truncated if its length exceeds the length of the buffer.
Buffer
MaxLength
%
The VanGetMsg( ) function returns 0 if the message fits in the buffer variable you provide. Otherwise, it truncates the error message to fit the length of the buffer variable and returns the actual length.
)-
The following program code attempts to open a connection with a Vantive server using the VanOpenConnection( ) function. If an error condition occurs during the attempt, the program uses VanGetMsg( ) to retrieve the error message.
long conn; char buff[100]; struct VanConnRecord cr; /* Other program code... */ cr.crName = Cervantes; cr.crPassword = quixote; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) {
4-86

&(
VanGetMsg(conn, buff, (long)sizeof(buff)); printf(%s, buff); /* Other error code... */ };

% 23

Use the VanNewRecord( ) function to create a new record for a form and fill the record with default values. The new record you create with VanNewRecord( ) is not saved automatically, so it doesnt exist in the database until you execute the VanSaveRecord( )function. Consequently, the new form is considered to contain unsaved, modified data.
VanNewRecord( )returns the error VAN_ECHANGED if
either the form or its subforms contain unsaved, modified data. When you execute VanNewRecord( ) on a subform, the function returns the error VAN_EEMPTY if the parent form is empty. If the parent form contains a new, unsaved record, the function returns the error VAN_NEWREC. The VanNewRecord( ) function will not create a new record for an inbox form. To create a new inbox action, use the VanPrepareAction( )function.
The VanNewRecord( ) function uses the following syntax:

long VanNewRecord(long FormHandle)
4-87

&(
9 ;
VanNewRecord FormHandle
The name of the VanNewRecord( ) function. An open form handle that was established earlier with the VanCreateMainForm( ) or VanCreateSubForm( ) function.
%
The VanNewRecord( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE

Invalid form handle (non-existent or inbox form handle). Parent form is empty. (This error condition only applies when you use VanNewRecord( ) on a subform.) Unable to set default values. Use VanGetMsg( ) to retrieve the text message. RPC timeout. Server operations did not return on time. The form or its subforms currently have modified, unsaved data. The parent forms record is a new record.
VAN_EEMPTY
VAN_EDEFAULT
VAN_ETIMEOUT
VAN_ECHANGED
VAn_ENEWREC
)-
The following program code uses the VanCreateMainForm( ) function to create a main form for case records, then uses VanNewRecord( ) to create a new record in the form.
4-88

&!
long form; long conn; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanNewRecord(form) < 0) { /* Failure code... */ };

VanCreateSubForm( ), VanCreateMainForm( ), VanSaveRecord( ), VanUndoChanges( )

23
Use the VanNumChilds( ) function to get the number of subforms available for a main form. You create subforms with the VanCreateSubForm(
)function.
The VanNumChilds( ) function uses the following syntax:

long VanNumChilds(long FormHandle)
9 ;
VanNumChilds FormHandle
The name of the VanNumChilds( ) function. An open handle for a main form that was established earlier with the VanCreateMainForm( )function.
4-89

&!
%
When successfully executed, the VanNumChilds( ) function returns the number of subforms defined for the given main form. When an error condition occurs, VanNumChilds( ) returns either of the following values:

VAN_EHANDLE VAN_EMEMORY

Invalid form handle. Out of memory.
)-
The following program code uses the VanCreateMainForm( ) function to create a main form for case records. Later, the program uses the VanNumChilds( ) function to store the total number subforms in a variable named count.
long conn; long count; long mform; /* Other program code... */ if ((mform = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; / * Other program code... */ count = VanNumChilds(form);

VanCreateMainForm( ), VanCreateSubForm( ), VanCreateInboxForm( ), VanFieldDesc( )
4-90

&!
"
23
Use the VanNumFields( ) function to get the number of fields in an active form.
VanNumFields( ) only counts the defined fields accessible by the VanFieldDesc( )function.
The VanNumFields( ) function uses the following syntax:

long VanNumFields(long FormHandle)
9 ;
VanNumFields FormHandle
The name of the VanNumFields( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
%
When successfully executed, the VanNumFields( ) function returns the number of fields in the given main form. When an error condition occurs (due to an invalid FormHandle value), VanNumFields( ) returns VAN_EHANDLE.
)-
The following program code uses the VanCreateMainForm( ) function to create a main form for case records, then uses the VanNumFields( ) function to store the total number subforms in a variable named numflds.
long conn; long form;
4-91

)*
long numflds; /* Other program code... */ if ((mform = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; if ((numflds = VanNumfields(form)) < 0) { /* Failure code... */ };

VanFieldDesc( )
5 23

Use the VanOpenConnection( ) function to open a connection to a Vantive server. Executing VanOpenConnection( ) returns a handle that identifies the new connection. Use this handle as the ConnectionHandle argument when you open forms with the VanCreateInboxForm( ) and VanCreateMainForm( )functions, and when you close the connection later with the VanCloseConnection( )function. In the current version of Vantive API, only one outstanding connection is allowed at a time. Any attempt to make more than one connection generates the error VAN_EMAXCONN.
The VanOpenConnection( ) function uses the following syntax:

long VanOpenConnection(long Ver-
4-92

)*
sion, struct VanConnRecord *ConnRecord)
9 ;
VanOpenConnection Version
The name of the VanOpenConnection( ) function. The Vantive API version number that the calling program is written for. This version number must match the current version of the API or an earlier version. A pointer to the structure VanConnRecord, which contains login information on the user and the server host and port.
ConnRecord
%
The VanOpenConnection( ) function returns a value greater than or equal to 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EMEMORY VAN_EMAXCONN VAN_ELOGIN VAN_EVERSION VAN_EARG

Out of memory. Maximum number of connections exceeded. Error found during login request. Invalid or unsupported version number. Invalid VanConnRecord element (required information is missing). RPC timeout. Server operations did not return on time.
VAN_ETIMEOUT
)-
The following program code uses the VanOpenConnection( ) function to open a connection to a Vantive server host and port, creating a connection
4-93

)*
handle and storing it in a variable named conn. Later, the program closes the connection with the VanCloseConnection( ) function.
long conn; long xform; struct VanConnRecord cr; cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if (VanCloseConnection(conn, 1L, (long *)0) == 0) { /* Success code */ };

VanCloseConnection( ), VanCreateInboxForm( ), VanCreateMainForm( )
5
23
Use the VanOpenCursor( ) function to open a cursor on the Vantive server and prepare it for subsequent fetch operations. You can use VanOpenCursor( ) to prepare the search and retrieval of main object, popup records, or inbox records. The search can have an optional search qualifier and an optional order by clause (in addition to the qualifications already created using the VanAddQualifier( ) calls).
4-94

)*
The function bases a search operation on a subform on the object type, object id of the record in the main form, and the search criteria specified in the where clause of the Make Info Popup form. The function can further qualify the search by adding where clause. If you omit the where clause, the fetch operation returns an unsuitably large result set. If you omit the order by clause, the ordering of the returned data is undefined. If the main form is empty, executing VanOpenCursor( ) on a subform generates the VAN_EEMPTY error. If a form contains modified and unsaved data, executing VanOpenCursor( ) generates the VAN_ECHANGED error.
The VanOpenCursor( ) function uses the following syntax:

long VanOpenCursor(long FormHandle, char *WhereClause, char *OrderBy)
9 ;
VanOpenCursor FormHandle
The name of the VanOpenCursor( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
4-95

)*
WhereClause
An optional search clause that determines which records are accessed by the cursor. The clause must be in valid SQL form, without the keyword where. You can also specify a where clause using Vantive column path syntax. (See VanAddQualifer( ) function in this chapter.) An optional order by clause that determines the order of returned records. The clause must be in valid SQL form, without the keywords order by.
OrderBy
%
The VanOpenCursor( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EEMPTY VAN_ECHANGED VAN_EOPEN

Invalid form handle. Form is empty. There is modified data in either the form or a subform. Error found during cursor opening.
)-
The following program code uses the VanCreateMainForm( )and VanOpenCursor( ) functions to create a main form and open a cursor for the form. At a later time, the program uses VanCloseCursor( ) to close the cursor.
long conn; long form; /* Other program code... */ if ((form = VanCreateMain-
4-96

)* !
Form(conn, CASE)) < 0) { /* Failure code... */ }; if (VanOpenCursor(form, swF > 5, (char *)0) == 0) { /* Success code... */ }; /* Other program code... */ if (VanCloseCursor(form) < 0) { /* Failure code... */ };

VanAddQualifier( ), VanCloseCursor( ), VanFetchRecord( ), VanCreateInboxForm( ), VanCreateMainForm( ), VanCreateSubForm( )
5 )- 23

Use the VanOpenExtDocument( ) function to initiate access to an external document from the Research Agent server. Once you retrieve the document, you can retrieve each line of the document through calls to VanExtDocLine( ). You can retrieve DocId values using the VanGetDocId( ) function. The VanOpenExtDocument( ) function decrements the value every time the retrieval process times out (that is, waiting for more text from the text server). If the value hits zero and the server still has not retrieved the whole document, the VanOpenExtDocument( ) function returns the VAN_EDOCTIMEOUT error.
4-97

)* !
The VanOpenExtDocument( ) function uses the following syntax:

long VanOpenExtDocument(long ConnectionHandle, char *DocId, long NumRetries)
where:
VanOpenExtDocument ConnectionHandle
The name of the VanOpenExtDocument( ) function. A valid connection handle that was established earlier with the VanOpenConnection( ) function. A documentation identification string. Number of retries if the retrieval process times out. NumRetries can be either 0 or any positive integer value.
DocId NumRetries
%
The VanOpenExtDocument( ) function returns the document handle when it executes successfully; otherwise, it returns any of the following values:

VAN_EMEMORY VAN_EHANDLE VAN_EDOCTIMEOUT VAN_EOPENDOC

Out of memory. Invalid form handle. Document retrieval times out. Error retrieving document.
4-98

)* !
)-
The following program code uses the VanOpenConnection( ) function to open a connection to a Vantive server host and port, creating a connection handle and storing it in a variable named conn. It then uses the VanCreateMainForm( ) function to open the main form for a record type. Finally, the program uses the VanGetDocId( ) function to get the external document identification value, which you can use in subsequent VanOpenExtDocument( ) calls to retrieve the document.
long conn; char docId[30]; long form; long status; struct VanConnRecord cr; struct VanData data; cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ data.vdPtr = malloc(20); data.vdLength = 20; data.vdType = VAN_TCHAR; if ((docId = VanGetDocId(ralist, &data)) < 0)
4-99

*

{ /* Failure code... */ }; if ((status = VanOpenExtDocument(conn, docId, 1L)) < 0) { /* Failure code... */ };

VanCloseExtDocument( ), VanExtDocLine( ), VanGetDocId( )
23

Use the VanPrepareAction( ) function to start a new Action Request. Executing VanPrepareAction( ) generates an action handle that identifies the Action Request for other API functions. For example, you can use this handle as the ActionHandle argument for the VanAddActionReceiver( )function (which adds a name to the recipient list for the Action Request) and the VanDoAction( )function (which executes the Action Request). The Action argument of VanPrepareAction( ) determines the type of action to be performed by the Action Request. However, which actions can be performed depends on the type of form you specify with the FormHandle argument. For example, if the Action Request performs a send action, the form handle must be that of a main form that contains a valid object. If the Action Request performs a Forward, Mark-As-Done, or Mark-As-Cancelled action, the form handle must be that of an inbox form that contains a valid inbox action.
4-100

*

No more than 8 Action Requests can be in the preparation stage at a time, and exceeding this limit generates the error VAN_EMAXACT. However, executing the VanDoAction( ) or VanStopAction( ) function on any outstanding Action Request removes it, allowing the creation of another Action Request. Executing VanPrepareAction( ) on a subform generates the error VAN_EHANDLE.
The VanPrepareAction( ) function uses the following syntax:

long VanPrepareAction(long FormHandle, long Action)
9 ;
VanPrepareAction FormHandle
The name of the VanPrepareAction( ) function. An open form handle that was established earlier with the VanCreateInbox( ) or VanCreateMainForm( ) function. The inbox action type.
Action
%
The VanPrepareAction( ) function returns an action handle when it executes successfully; otherwise, it returns any of the following values:

VAN_EMAXACT VAN_EEMPTY

Maximum number of actions exceeded. The form (or inbox) does not contain a valid object (or inbox action).
4-101

*

VAN_EHANDLE VAN_EMEMORY VAN_EACTTYPE VAN_ETIMEOUT

Invalid or inappropriate form handle. Out of memory. Illegal action type. RPC timeout. Server operations did not return on time.
)-
The following program code uses the VanPrepareAction( ) function to create an Action Request and uses the VanAddActionReceiver( ) function to add a recipient group named TechSupport to the recipient list of the Action Request. It then uses the VanDoAction( ) function to perform the Action Request.
long form; long action; struct VanActRcv r; /* Other program code... */ action = VanPrepareAction(form, VAN_ASEND); r.vaRType = VAN_RINBOX; r.vaLength = -1; r.vaIsCC = 0; if (VanAddActionReceiver (action, &r) < 0) { /* Failure code */ }; /* Other program code... */ if (VanDoAction(action) < 0) { /* Failure code */ };
4-102

!

VanAddActionReceiver( ), VanCreateInboxForm( ), VanCreateMainForm( ), VanDoAction( ), VanSetActionProperty( ), VanStopAction( )
23
VanAPI can create a new attachment to an open object. It is up to the application to insert the necessary OLE2 control information inside the attachment file before creating the new attachement (using the VanPutAttachment ( ) function). Otherwise, this new attachment created by VanAPI cannot be viewed by the user interface. Use the VanPutAttachment( ) function to create an attachment for an open object. You can create an attachment for an open object by calling the VanPutAttachment( ) function one time or several times, depending on whether you have enough buffer capacity to hold all of the data.
The VanPutAttachment( ) function uses the following syntax:

long VanPutAttachment(long AttachmentFormHandle, struct VanData *Title, unsigned long totalLen, struct VanData *Data)
4-103

!
9 ;
VanPutAttachment AttachmentFormHandle
The name of the VanPutAttachment( ) function. An open form handle that was established earlier with the VanCreateAttachmentForm( ) function. A pointer to the struct VanData, which contains the attachment title. The total length of the attachment data. A pointer to the structure VanData, which receives data from the action note when you execute the VanGetActionNote( ) function
Title
TotalLen Data
%
The VanPutAttachment( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EARG VAN_ENEWATTACH VAN_ESTARTBLOB

Invalid form handle. Invalid output data description. Cannot create new attachment. The Blob (Binary Large Object) has already started. Get Blob error.
VAN_EGETBLOB
)-
The following program code uses the VanOpenConnection( ) function to establish a connection to the Vantive server and port, and uses the VanCreateMainForm( )function to open the Main
4-104

!
Information form for case records. It then uses VanCreateAttachmentForm ( ) to create an instance of an attachment form named swAttachmentPu, which is created with Vantive Edit for the current user group. Finally, it uses VanPutAttachment ( ) to create a new attachment for this form.
struct VanConnRecord cr; struct VanData data; cr.crName = Max; cr.crPassword = xsecret; cr.crHost = titan; cr.crPort = 2000; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ } if ((aform = VanCreateAttachmentForm(form,sw AttachmentPu)) < 0) { /* Failure code */ } /* Other program code... */ data.vdType = VAN_TCHAR; data.vdLength = 11; data.vdPtr = Hello World!;
4-105

title.vdType = VAN_TCHAR; title.vdLength = 8; title.vdPtr = test.txt; if ( VanFetchRecord (form) == 0) { /* Other program code... */ if (( VanPutAttachment (aform, &title, 11, &data) < 0 ) ) { /* failure code */ };

VanOpenConnection( ), VanCreateMainForm( ), VanCreateAttachmentForm( ), VanFetchRecord( )
%

23
Use the VanRecordStatus( ) function to determine if a record contains modified, unsaved data. A record in a form is said to have modified status if any of the following have occurred, and the record was not saved afterward:
The form was just created with the VanNewRecord()function. The form was modified with the VanSetField()function. The form is a main form, and any of its subforms were modified.
4-106

If the form you evaluate with VanNewRecord( ) contains modified data, the handle of that form is returned through the ModFormHandle argument. If the form you evaluate contains no modified data but any subforms do, the handle for one of those subforms is returned.
The VanRecordStatus( ) function uses the following syntax:
long VanRecordStatus(long FormHandle, long *ModFormHandle)
9 ;
VanRecordStatus FormHandle
The name of the VanRecordStatus( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. An pointer to a buffer that receives the handle of the main form or subform containing modified data.
ModFormHandle
%
The VanRecordStatus( ) function returns 0 when no modified data are found in the evaluated form or any subform. Otherwise, it returns any of the following values:

VAN_ECHANGED VAN_EHANDLE VAN_EEMPTY

Modified, unsaved data found. Invalid or inappropriate form handle. The form contains no record.
4-107

%
)-
The following program code uses the VanCreateMainForm( ) function to create a main form for case records, then uses the VanNewRecord( ) function to create a new record in the form. Later, the VanRecordStatus( ) function tests the record to see if changes were made.
long form; long conn; long modform; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; if (VanNewRecord(form) < 0) { /* Failure code... */ }; /* Other program code... */ status = VanRecordStatus(form, &modform);

VanNewRecord( ), VanSetField( ), VanUndoChanges( )
%
'(

Use the VanRestartInfoList( ) function to set the value pointer in an info list to the beginning of the list, allowing processing of the list from the start again.
VanRestartInfoList( ) can be called at anytime during
the existence of the info list.
4-108

%
The VanRestartInfoList( ) function uses the following syntax:

long VanRestartInfoList(long InfoHandle)
9 ;
VanRestartInfoList InfoHandle
The name of the VanRestartInfoList( ) function. The info list handle that was established earlier with the VanGetInfoList( ) function.
%
The VanRestartInfoList( ) function returns 0 when it executes successfully; otherwise, it returns the following value:

VAN_EHANDLE

Invalid info handle.
)-
The following program code establishes a connection to a Vantive host and port, creating a connection handle named conn. Later, the program starts an info list (for a list box) with the VanGetInfoList( ) function, creating an info list handle named info. Thereafter, each time the program executes VanGetInfoItem( ), the pointer is set to the next item in the list. Later, the program sets the pointer back to the beginning of the list with the VanRestartInfoList( ) function.
long conn; long info; struct VanConnRecord cr; struct VanData d;
4-109

char inboxName[100]; cr.crName = cervantes; cr.crPassword = quixote; cr.crHost = spain; cr.crPort = 1619; if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code... */ }; /* Other program code... */ info = VanGetInfoList(conn, VAN_GINBOX, VAN_GDALL); /* Other program code... */ while (1) { /* Code using VanGetInfoItem( )... */ } VanRestartInfoList(info);

VanFreeInfoList( ), VanGetInfoItem( ), VanGetInfoList( )
% 23

Use the VanSaveRecord( ) function to save the record that currently resides in a form. Before VanSaveRecord( ) saves a record, it verifies the data it contains (including foreign key lookups). If any field is found to be incomplete or incorrect, VanSaveRecord( ) aborts execution and returns an error. If the record has not changed since the last save, VanSaveRecord( ) does not save the record, and returns VAN_WNOSAVE.
4-110

If no further manipulation is required after the save, specify a value of 0 for the Refresh argument. This prevents Vantive API from retrieving the updated record again after the save, and the form is considered to be empty. Before and after the save, VanSaveRecord( ) checks whether there are any events associated with this save record action. If there are events, VanSaveRecord( ) triggers the events according to the event types.
The VanSaveRecord( ) function uses the following syntax:

long VanSaveRecord(long FormHandle, struct VanSFInfo *SFInfo, long Refresh)
9 ;
VanSaveRecord FormHandle
The name of the VanSaveRecord( ) function. An open form handle that was established earlier with the VanCreateMainForm( ) or VanCreateSubForm( ) function. A pointer to the structure VanSFInfo, which receives information on the column that caused a problem (if any) during the attempt to execute VanSaveRecord( ). Use the information in this structure to diagnose the error condition after attempt. A flag that determines if the record is refreshed (reloaded) after a successful save. To reload the record after saving, set this flag to a non-zero value.
SFInfo
Refresh
4-111

%
The VanSaveRecord( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EEMPTY VAN_ECHANGED VAN_ESAVE

Invalid or inappropriate form handle. The form contains no record. Modified, unsaved data found. Error(s) found during save. Use VanGetMsg( ) to get the error message text. RPC timeout. Server operations did not return on time.
VAN_ETIMEOUT
)-
The following program code uses the VanCreateMainForm( )function to open a main form for case records and creates a new record with the VanNewRecord( ) function. Later, it uses VanSaveRecord( ) to save the record and reload it automatically.
long conn; long form; struct VanSFInfo sfInfo; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code */ }; /* Other program code... */ if (VanNewRecord(form) < 0) {
4-112

/* Failure code... */ }; /* Other program code... */ if (VanSaveRecord(form, &sfInfo, 1L) < 0) { /* Failure code using sfInfo data... */ };

VanNewRecord( ), VanSetField( )
23
Use the VanSearchCount( ) function to get the number of records (the size of the data set) that the current cursor returns. Before you can call VanSearchCount( ) successfully, you must use VanOpenCursor( )to set up a cursor for an existing form. You can use the value returned by VanSearchCount( ) to determine the number of times a looping statement must execute the VanFetchRecord( ) function to move through a series of records accessed by the cursor. However, the size of the data set may change over time, so the value returned by VanSearchCount( ) might not agree with the total number of records at a later time. For example, in an environment where a large number of users add records to the database, the value returned by VanSearchCount( ) could be rendered inaccurate in a short amount of time. For this reason, it is advisable to execute VanSearchCount( ) and the first VanFetchRecord( )call without pause in between to minimize the potential difference.
4-113

The VanSearchCount( ) function uses the following syntax:

long VanSearchCount(long FormHandle)
9 ;
VanSearchCount FormHandle
The name of the VanSearchCount( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
%
The VanSearchCount( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EFETCH

Invalid form handle. Found error(s) during counting. Use VanGetMsg( ) to retrieve the text message. Cursor is not open (VanOpenCursor( ) was not executed successfully). RPC timeout. Server operations did not return on time.
VAN_ECURSOR
VAN_ETIMEOUT
)-
The following program code uses the VanOpenConnection( ) function to open a connection to a Vantive server host and port. Later, VanCreateMainForm( ) and VanOpenCursor( ) functions create a main form and open a cursor for the
4-114

form. If execution of VanOpenCursor( ) is successful, VanSearchCount( ) places the total number of rows returned by the cursor in a variable named count.
long conn; long form; long count; struct VanConnRecord cr; /* Other program code... */ if ((conn = VanOpenConnection(1L, &cr)) < 0) { /* Failure code */ }; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanOpenCursor(form, swF > 5, (char *)0) == 0) { /* Success code... */ if ((count = VanSearchcount(form)) < 0); { /* Failure code... */ }; };

VanCloseCursor( ), VanFetchRecord( ), VanCreateInboxForm( ), VanCreateMainForm( ), VanCreateSubForm( ), VanOpenCursor( )
4-115

*
23

Use the VanSetActionProperty( ) function to modify an Action Request. You specify which modification to make with the
ActionProperty argument. The values you can specify for ActionProperty depend on the Action Requests action type,
which you specified previously with the second argument (Action) of the VanPrepareAction( )function. The following restrictions apply: You can specify the action property VAN_PNOTE for Send or Forward actions only. You can specify properties VAN_PINBACT, VAN_PPRIORITY, VAN_PRECEIPT, and VAN_PACTREQ for Send actions only. When you execute VanSetActionProperty( ), you must specify a value for the bind variable. The bind variable contains information needed to modify the Action Request. For example, to change the priority of an Action Request to High, set the ActionProperty argument to VAN_PPRIORITY and assign the bind variable a value of High. The bind variable is pointed to by vdPtr, an element of the Vantive API structure VanData. You specify the data type of the bind variable with another element of the VanData structure, vdType. This data type must be compatible with the action property type (which you specify with Action, the second argument of the VanSetActionProperty( ) function). The requirements are as follows:
When you specify the VAN_PINBACT or VAN_PPRIORITY action property, you need the bind variable type VAN_TCHAR.
4-116

*
When you specify the VAN_PRECEIPT action property, you need to allow VAN_TCHAR as an argument to SetActionProperty( ). If the value in VAN_TCHAR is invalid (that is, non-numeric value), the function returns the VAN_ETYPE error. When you specify the VAN_PNOTE action property, you need the bind variable type VAN_TCHAR or VAN_TNULL.
All action properties may have default values (as defined by the database). When such default values exist, the API program does not have to set all action properties. To send an action, the calling program can call VanPrepareAction( ), VanAddActionReceiver( ), and VanDoAction( )without calling VanSetActionProperty( ) at all. Because they are customizable, the values of the action properties such as VAN_PINBACT and VAN_PPRIORITY may differ from installation to installation. The API verifies any user-defined values against the list of acceptable values that it obtains from the database. If the value does not exist in the list, VanSetActionProperty( ) returns the VAN_EVALUE error.
The VanSetActionProperty( ) function uses the following syntax:
long VanSetActionProperty(long ActionHandle, long ActionProperty, struct VanData *Data)
4-117

*
9 ;
VanSetActionProperty
The name of the VanSetActionProperty( ) function. An identifier for the Action Request to modify. Use the VanSetActionProperty( ) function to create this handle. A valid action property type. This type must be compatible with the kind of action that is modified. A pointer to the structure VanData, which contains bind variable type, the action request description, and the length of the request description. The length is -1 if the bind variable is a null-terminated string.
ActionHandle
ActionProperty
Data
%
The VanSetActionProperty( ) function returns an action handle when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_EACTTYPE VAN_ETYPE VAN_EVALUE

Invalid or inappropriate form handle. Illegal action type. Invalid bind variable type for the action properties. Invalid action property type.
)-
The following program code uses the VanPrepareAction( ) function to create an Action Request, then uses VanSetActionProperty( ) to change the action request code to Research/Reply. Later, the VanDoAction( ) function performs the changed action.
4-118

long form; long act; struct VanActRcv r; /* Other program code... */ act = VanPrepareAction(form, VAN_ASEND); /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = Research/Reply; d.vdLength = -1; if (VanSetActionProperty(act, VAN_PINBACT, &d) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanDoAction(act) < 0) { /* Failure code */ };

VanAddActionReceiver( ), VanCreateInboxForm( ), VanCreateMainForm( ), VanDoAction( ), VanPrepareAction( ), VanStopAction( )
" 23

Use this function to change the contents of a form field. If the form is empty, VanSetField( ) returns the error VAN_EEMPTY. If the data value you insert in the form field with VanSetField( ) is identical to the data that already exists in the field, the record status (as revealed by the
4-119

VanRecordStatus( )function) remains unchanged. If the
new data value is different from the data that already exists, the record status changes to modified. can only modify a form field value as permitted by the fields definitions. For example, if the form field does not have update permission, VanSetField( ) returns the error VAN_EPERM for the column path.
VanSetField( ) VanSetField( )
verifies each data item you specify before storing it in its buffer. If the field is DROP DOWN, the data item is compared against the effective list for that field.
The ColumnPath argument specifies the column path of the field to change. If the ColumnPath setting completes a search group, the foreign key lookup starts automatically. If the setting completes multiple search groups, the foreign keys are searched one at a time in the alphabetical order of the search group names, unless there is already a failed foreign key lookup from an earlier VanSetField( ) call. If that case, VanSetField( ) attempts to look up the search groups foreign key first before going through all the other search groups.
-
The VanSetField( ) function uses the following syntax:

long VanSetField(long FormHandle, char *ColumnPath, struct VanData *Data, struct VanSFInfo *SFInfo)
9 ;
VanSetField FormHandle
The name of the VanSetField( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
4-120

ColumnPath
A path to the column of the field you change with VanSetField( ). A pointer to the structure VanData, which contains information on the value to insert in the form field. A pointer to the structure VanSFInfo, which receives information on any error condition that is generated during execution of VanSetField( ).
Data
SFInfo
%
The VanSetField( ) function returns 0 when it executes successfully; otherwise, it returns any of the following values:

VAN_EHANDLE VAN_ETYPE VAN_EFIELD VAN_EPERM VAN_ETOOLONG VAN_EVALUE VAN_ESGMANY VAN_ESGNONE VAN_ENOTGRP

Invalid or inappropriate form handle. Invalid users data type. Column path value specified in ColumnPath is invalid. User cannot change the value in the field. Data is too large or too long. Value is invalid for the column path. Search group completion returns many values. Search group completion returns no value. Column path is not part of an unsuccessful looked up search group. RPC timeout. Server operations did not return on time.
VAN_ETIMEOUT
4-121

*
)-
The following program code uses the VanCreateMainForm( )function to create a form for case records. Later, it uses the VanSetField( ) function to place the character string This is an example into a field named swNote. If an error occurs during execution of this function, the error number is printed out.
long form; long conn; unsigned long repid; struct VanData d; struct VanSFInfo errInfo; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ } /* Other program code... */ d.vdType = VAN_TCHAR; d.vdPtr = This is an example; d.vdLength = -1; if (VanSetField(form, swNote, &d, &errInfo) < 0) { printf(%d, errInfo.vsECode); /* Other error code... */ };

VanNewRecord( ), VanSaveRecord( ), VanUndoChanges( )
23
Use the VanStopAction( ) function to cancel an Action Request that is currently prepared for execution.
4-122

*
You create Action Requests with the VanPrepareAction( )function, which creates an action handle that identifies the request. No more than 8 Action Requests can be in the preparation stage at a time, and attempting to exceed this limit generates an error. However, executing the VanStopAction( ) function on any outstanding Action Request removes the request and frees its handle, allowing the creation of another Action Request. A related function, VanDoAction( ), executes the request before removing it and freeing its handle.
The VanStopAction( ) function uses the following syntax:

long VanStopAction(long ActionHandle)
9 ;
VanStopAction ActionHandle
The name of the VanStopAction( ) function. An identifier for the Action Request. Use the VanPrepareAction( ) function to create this handle.
%
The VanStopAction( ) function returns 0 when it executes successfully; otherwise, it returns either of the following values:

VAN_EHANDLE VAN_ETIMEOUT

Invalid action handle. RPC timeout. Server operations did not return on time.
4-123

+

)-
The following program code uses the VanPrepareAction( ) function to create an Action Request and uses the VanAddActionReceiver( )function to add a recipient group named TechSupport to the recipient list of the Action Request. Later, it uses the VanStopAction( ) function to cancel the Action Request and release its handle.
long form; long action; struct VanActRcv r; /* Other program code... */ action = VanPrepareAction(form, VAN_ASEND); r.vaRType = VAN_RINBOX; r.vaLength = -1; r.vaIsCC = 0; if (VanAddActionReceiver (action, &r) < 0) { /* Failure code */ }; /* Other program code... */ if (VanStopAction(action) < 0) { /* Failure code */ };

VanDoAction( ), VanPrepareAction( )
,#
23
Use the VanUndoChanges( ) function to undo all changes to an existing record if it was changed with VanSetField( )and not saved, or discard the record altogether if it was created with the VanNewRecord( )function and not saved.
4-124

+

To undo changes in a form without undoing changes in any of its subforms, set the UndoAll argument of VanUndoChanges( ) to 0. If the form is a main form and any of its subforms contain changes, VanUndoChanges( ) returns the error VAN_ECHANGED. To undo changes in a form and all of its subforms, set the UndoAll argument to a nonzero value. If the current record does not yet exist in the database (as when you create a new record with VanNewRecord( ) without saving it with VanSaveRecord( )),executing VanUndoChanges( ) discards the record and restores the form to the state it was in before the new record was created. For example, if the form contained a record that was fetched with the VanFetchRecord( )function before the creation of the new record, the fetched record is returned to the form and is accessible. Executing VanUndoChanges( ) generates no error if the record in the form is unchanged.
The VanUndoChanges( ) function uses the following syntax:

long VanUndoChanges(long FormHandle, int UndoAll)
9 ;
VanStopAction FormHandle
The name of the VanStopAction( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. A flag that determines if executing VanUndoChanges( ) undoes changes in subforms.
UndoAll
4-125

+

%
The VanUndoChanges( ) function returns 0 when it executes successfully; otherwise, it returns either of the following values:

VAN_EHANDLE VAN_EEMPTY VAN_ECHANGED

Invalid or inappropriate form handle. Form is empty. One or more subforms of the form contain updated data.
)-
The following program code uses the VanCreateMainForm( )function to open a main form for case records and creates a new record with the VanNewRecord( ) function. Later, it uses VanUndoChanges( ) to undo any changes that are made to the record.
long conn; long form; /* Other program code... */ if ((form = VanCreateMainForm(conn, CASE)) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanNewRecord(form) < 0) { /* Failure code... */ }; /* Other program code... */ if (VanUndoChanges(form, 0) < 0) {
4-126

+

/* Failure code... */ };

VanNewRecord( )
4-127

+

4-128

)-

Vanperl is a version of the perl utility, and includes extensions for accessing Vantive applications. These extensions include the equivalents of all twenty-seven Vantive API functions.
" )&
Vanperl functions are almost identical to the functions of Vantive API. For example, they have the same names, return the same values, and perform the same operations. However, the Vanperl equivalents do not use structures (such as VanData or VanConnRecord) as input and output arguments. Instead, the Vanperl functions express all data items as individual arguments. Each structure used by a Vantive API function contains multiple elements, and is referenced in the functions argument list with a single pointer value. Vanperl functions express each input and output value as an individual argument. Consequently, some Vanperl functions have more arguments than their Vantive API counterparts.

When starting the Vanperl program, type use Vanperl; in order to load the Vanperl module.
A-1
Vanperl Extensions

* *
% 23

The Vanperl VanAddActionReceiver( ) function uses the following syntax:
$ret = VanAddActionReceiver($ActionHandle, $vaRType, $vaIsCC, $vaReceiver)
9 ;
VanAddActionReceiver
The name of the VanAddActionReceiver( ) function. A handle value that identifies the Action Request. Use the VanPrepareAction( ) function to create this handle. The type of action receiver. (See Chapter 3, Action Receiver Types.) The length of the recipient name you specify with vaReceiver. Specify -1 if the string is nullterminated. (See Chapter 3, Managing Action Receiver Information.) The name of the recipient. (See Chapter 3, Managing Action Receiver Information.)
$ActionHandle
$vaRType
$vaIsCC
$vaReceiver
4 ' 23

The VanAddQualifier( ) function uses the following syntax:
$ret = VanAddQualifier($FormHandle, $ColumnPath, $Operator, $Data, $DataLength)
A-2
Vanperl Extensions

* *
9 ;
VanAddQualifier $FormHandle
The name of the VanAddQualifier ( ) function. The form handle value returned by the VanCreateMainForm( ) function, VanCreateSubForm( ) function, or the VanCreateInboxForm( ) function. The column path of the form field where you apply the qualification. The operator to use for qualification. The value to use for qualification. The length of the output variable $Data.
$ColumnPath
$Operator $Data $DataLength

23
VanChildDesc( )
function uses the following syntax:
$ret = VanChildDesc($FormHandle, $ChildNumber, $DescItem, $Data, $DataLength)
9 ;
VanChildDesc $FormHandle
The name of the VanChildDesc( ) function. An identifier for the main form. FormHandle must identify the main form; otherwise, an error condition is generated. The subform index, a positive whole number that identifies each subform. The range for this number is between 1 and the total number of subforms, which you obtain with the VanNumChilds( ) function. The subform information to request. You must specify VAN_CNAME (to get the name of the subform) or VAN_CLABEL (to get the label of the subform).
$ChildNumber
$DescItem
A-3
Vanperl Extensions

* *
$Data
An output variable that receives information on the subform when you execute the VanChildDesc( ) function. (See Chapter 3, Using Bind Variables.) The length of the output variable Data.
$DataLength

23
The VanCloseConnection( ) function uses the following syntax:
$ret = VanCloseConnection($ConnectionHandle, $AbortIfChanged, [$ModFormHandle])
9 ;
VanCloseConnection $ConnectionHandle
The name of the VanCloseConnection( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function. A value that determines if a connection is to be closed regardless of whether any changed data in the associated forms are saved. If you set the value of AbortIfChanged to zero, the connection is always closed; otherwise, if data remain unsaved, VanCloseConnection( ) returns VAN_ECHANGED, leaving the connection open. An optional output variable that automatically receives the handle value of the first form encountered containing modified, unsaved data. Use this handle later to identify, evaluate, and manipulate the form and its contents.
$AbortIfChanged
$ModFormHandle

23
The VanCloseCursor( ) function uses the following syntax:
$ret = VanCloseCursor($FormHandle)
A-4
Vanperl Extensions

* *
9 ;
VanCloseCursor $FormHandle
The name of the VanCloseCursor( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.

)- 23
The VanCloseExtDocument( ) function uses the following syntax:
$ret = VanCloseExtDocument($DocumentHandle)
9 ;
VanCloseExtDocument
The name of the VanCloseExtDocument( ) function. A valid document handle that was established earlier with the VanOpenExtDocument( ) function.
$DocumentHandle

"23
The VanCloseForm( ) function uses the following syntax:
$ret = VanCloseForm($FormHandle, $AbortIfChanged, [$ModFormHandle])
9 ;
VanCloseForm $FormHandle
The name of the VanCloseForm( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
A-5
Vanperl Extensions

* *
$AbortIfChanged
A value that determines if the form is always closed regardless of whether any changed data in the form or its subforms are saved. If you set AbortIfChanged to zero, the form and its subforms are always closed; otherwise, if any data remain unsaved, VanCloseForm( ) leaves the forms open and returns VAN_ECHANGED. An optional output variable that automatically receives the handle value of the first form encountered containing modified, unsaved data. Use this handle later to identify, evaluate, and manipulate the form and its contents.
$ModFormHandle
+

"23
The VanCreateActionHistoryForm( ) function uses the following syntax:
$ret = VanCreateActionHistoryForm($MainFormHandle, $ScreenName)
9 ;
VanCreateActionHis toryForm $MainFormHandle
The name of the VanCreateActionHistoryForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the screen.
$ScreenName
"23

The VanCreateAttachmentForm( ) function uses the following syntax:
$ret = VanCreateAttachmentForm($MainFormHandle, $ScreenName)
A-6
Vanperl Extensions

* *
9 ;
VanCreateAttachmen tForm $MainFormHandle
The name of the VanCreateAttachmentForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the screen.
$ScreenName
"23
The VanCreateChildDetailForm( ) function uses the following syntax:
$ret = VanCreateChildDetailForm($MainFormHandle, $SummaryScreenName)
9 ;
VanCreateChildDeta ilForm $MainFormHandle
The name of the VanCreateChildDetailForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the summary screen.
$SummaryScreenName
-"23
The VanCreateInboxForm( ) function uses the following syntax:
$formHandle = VanCreateInboxForm($ConnectionHandle, $InboxName)
9 ;
VanCreateInboxForm
The name of the VanCreateInboxForm( ) function.
A-7
Vanperl Extensions

* *
$ConnectionHandle
A connection handle established earlier with the VanOpenConnection( ) function. The name of an inbox which is accessible by the current user.
$InboxName
$ "23
The VanCreateMainForm( ) function uses the following syntax:
$formHandle = VanCreateMainForm($ConnectionHandle, $ObjectType)
9 ;
VanCreateMainForm $ConnectionHandle
The name of the VanCreateMainForm( ) function. A connection handle that was established earlier with the VanOpenConnection( ) function. The type of object to create the main form for.
$ObjectType
%(
23
The VanCreateRaList( ) function uses the following syntax:
$rahandle = VanCreateRaList($FormHandle, $Position)
9 ;
VanCreateRaList $FormHandle
The name of the VanCreateRaList( ) function. The valid form handle, established earlier with the VanCreateMainForm( ) function. The position of the object type to create a form handle for. This value must be larger than 0 and less than or equal to the count value returned by the VanDoResearch( ) function.
$Position
A-8
Vanperl Extensions

* *
"23
The VanCreateSubForm( ) function uses the following syntax:
$formHandle = VanCreateSubForm($MainFormHandle, $SubFormName)
9 ;
VanCreateSubForm $MainFormHandle
The name of the VanCreateSubForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the subform to open.
$SubFormName
"23

The VanCreateSummaryForm( ) function uses the following syntax:
$ret = VanCreateSummaryForm($MainFormHandle, $ScreenName)
9 ;
VanCreateSummaryForm
The name of the VanCreateSummaryForm( ) function. The form handle for main form, established earlier with the VanCreateMainForm( ) function. The name of the screen.
$MainFormHandle
$ScreenName
% 23

The VanDeleteRecord( ) function uses the following syntax:
$ret = VanDeleteRecord($FormHandle, $Recid)
A-9
Vanperl Extensions

* *
9 ;
VanDeleteRecord $FormHandle
The name of the VanDeleteRecord( ) function. The valid form handle, established earlier with the VanCreateMainForm( ) function.
$Recid
23
$ret = VanDoAction($ActionHandle)
The VanDoAction( ) function uses the following syntax:
9 ;
VanDoAction $ActionHandle
The name of the VanDoAction( ) function. An identifier for the Action Request. Use the VanPrepareAction( ) function to create this handle.
%
23
The VanDoResearch( ) function uses the following syntax:
$count = VanDoResearch($FormHandle, $Mode, $Text)
9 ;
VanDoResearch $FormHandle
The name of the VanDoResearch( ) function. Valid form handle established earlier with the VanCreateMainForm( ) function. The search mode. Text to use for the search (may be NULL or empty).
$Mode $Text
A-10
Vanperl Extensions

* *
)-( 23
The VanExtDocLine( ) function uses the following syntax:
$ret = VanExtDocLine($DocHandle, $LineNumber, $Data, $DataLength)
9 ;
VanExtDocLine $DocHandle
The name of the VanExtDocLine( ) function. A valid form handle that was established earlier with the VanOpenExtDocument( ) function. The text line number to retrieve. Output location for the retrieved text line. The length of the output variable $Data.
$LineNumber $Data $DataLength
)-( 23
The VanExtDocLineCount( ) function uses the following syntax:
$count = VanExtDocLineCount($DocHandle)
9 ;
VanExtDocLineCount $DocHandle
The name of the VanExtDocLineCount( ) function. Valid form handle that is established earlier with the function VanOpenExtDocument( ).
)-( $-( #23

The VanExtDocLineMaxLength( ) function uses the following syntax:
$length = VanExtDocLineMaxLength($DocHandle)
A-11
Vanperl Extensions

* *
9 ;
VanExtDocLineMaxLength
The name of the VanExtDocLineMaxLength( ) function. Valid form handle that is established earlier with the function VanOpenExtDocument( ).
$DocHandle
)- 23
The VanExtDocName ( ) function uses the following syntax:
$ret = VanExtDocName($DocHandle, $Data, $DataLength)
9 ;
VanExtDocName $DocHandle
The name of the VanExtDocName( ) function. Valid form handle established earlier with the function VanOpenExtDocument( ). A receiving variable for document name. The length of the receiving variable $Data.
$Data $DataLength
" % 23

The VanFetchRecord( ) function uses the following syntax:
$ret = VanFetchRecord($FormHandle)
9 ;
VanFetchRecord $FormHandle
The name of the VanFetchRecord( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
A-12
Vanperl Extensions

* *
"
23
The VanFieldDesc( ) function uses the following syntax:
$ret = VanFieldDesc($FormHandle, $FieldNumber, $DescItem, $Data, $DataLength)
9 ;
VanFieldDesc $FormHandle
The name of the VanFieldDesc( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. The form field number of the field to evaluate. The type of information to obtain from the form field. An output variable that receives information on the field when you execute the VanFieldDesc( ) function. The length of the output variable $Data.
$FieldNumber $DescItem $Data
$DataLength
23

The VanGetActionNote( ) function uses the following syntax:
$ret = VanGetActionNote($FormHandle, $Data, $Length)
9 ;
VanGetActionNote $FormHandle
The name of the VanGetActionNote( ) function. An open form handle established earlier with the VanCreateRaList( ) function. An output variable that receives information on the field when you execute the VanGetActionNote( ) function. The length of the output variable $Data.
$Data
$DataLength
A-13
Vanperl Extensions

* *
23

The VanGetAttachment( ) function uses the following syntax:
$ret = VanGetAttachment($FormHandle, $Data, $Length)
9 ;
VanGetAttachmen t $FormHandle
The name of the VanGetAttachment( ) function. An open form handle established earlier with the VanCreateRaList( ) function. An output variable that receives information on the field when you execute the VanGetAttachment( ) function. The length of the output variable $Data.
$Data
$DataLength
23

$ret = VanGetDocId($FormHandle, $Data, $DataLength)
9 ;
VanGetField $FormHandle
The name of the VanGetDocId( ) function. An open form handle established earlier with the VanCreateRaList( ) function. A receives document identification value upon function return. The length of the output variable $Data.
$Data
$DataLength
A-14
Vanperl Extensions

* *
" 23

$ret = VanGetField($FormHandle, $ColumnPath, $Data, $DataLength)
The VanGetField( ) function uses the following syntax:
9 ;
VanGetField $FormHandle
The name of the VanGetField( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. An output variable that receives data from the field when you execute the VanGetField( ) function. The length of the output variable $Data.
$ColumnPath
$Data
$DataLength
( '23
The VanGetLibInfo( ) function uses the following syntax:
$ret = VanGetLibInfo($ConnectionHandle, $InfoField, $Data, $DataLength)
9 ;
VanGetLibInfo $ConnectionHandle
The name of the VanGetLibInfo( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function. This argument is ignored for client library and Vantive API version requests.
A-15
Vanperl Extensions

* *
$InfoField
The version information to get. To identify the client library version, specify VAN_ICLIENT. To identify the Vantive server version, specify VAN_ISERVER. To identify the Vantive database dictionary version, specify VAN_IDB. To identify the Vantive API version, specify VAN_IVERSION. An output variable that receives the version string when you execute the VanGetLibInfo( ) function. The length of the output variable $Data.
$Data
$DataLength
$
#23
The VanGetMsg( ) function uses the following syntax:
$ret = VanGetMsg($ConnectionHandle, $Buffer, $MaxLength)
9 ;
VanGetMsg $ConnectionHandle
The name of the VanGetMsg( ) function. An open server connection handle that was established earlier with the VanOpenConnection( ) function. A character buffer that receives the error message. The text in this buffer is null-terminated. The size of the buffer. The error message is truncated if its length exceeds the length of the buffer.
$Buffer
$MaxLength
% 23

The VanNewRecord( ) function uses the following syntax:
$ret = VanNewRecord($FormHandle)
A-16
Vanperl Extensions

* *
9 ;
VanNewRecord $FormHandle
The name of the VanNewRecord( ) function. An open form handle that was established earlier with the VanCreateMainForm( ) or VanCreateSubForm( ) function.

23
The VanNumChilds( ) function uses the following syntax:
$ret = VanNumChilds($FormHandle)
9 ;
VanNumChilds $FormHandle
The name of the VanNumChilds( ) function. An open handle for a main form that was established earlier with the VanCreateMainForm( ) function.
"
23
The VanNumFields( ) function uses the following syntax:
$ret = VanNumFields($FormHandle)
9 ;
VanNumFields $FormHandle
The name of the VanNumFields( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
A-17
Vanperl Extensions

* *
5 23

The VanOpenConnection( ) function uses the following syntax:
$conn = VanOpenConnection($Name, $Password, $Host, $Port)
9 ;
VanOpenConnection $Name $Password
The name of the VanOpenConnection( ) function. The users login name. The users password. This value is required only if the user has a password. The host name to log on to. The port number to use.
$Host $Port
5
23
The VanOpenCursor( ) function uses the following syntax:
$ret = VanOpenCursor($FormHandle, $WhereClause, [$OrderBy])
9 ;
VanOpenCursor $FormHandle
The name of the VanOpenCursor( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. An optional search clause that determines which records are accessed by the cursor. The clause must be in valid SQL form, without the keyword where. An optional order by clause that determines the order of returned records. The clause must be in valid SQL form, without the keywords order by.
$WhereClause
$OrderBy
A-18
Vanperl Extensions

* *
5 )- 23

The VanOpenExtDocument( ) function uses the following syntax:
$dochandle = VanOpenExtDocument($ConnectionHandle, $DocId, $NumRetries)
9 ;
VanOpenExtDocument $ConnectionHandle
The name of the VanOpenExtDocument( ) function. A valid connection handle that was established earlier with the VanOpenConnection( ) function. A documentation identification string. Number of retries if the retrieval process times out.
$DocId $NumRetries
23

The VanPrepareAction( ) function uses the following syntax:
$action = VanPrepareAction($FormHandle, $Action)
9 ;
VanPrepareAction $FormHandle
The name of the VanPrepareAction( ) function. An open form handle that was established earlier with the VanCreateInbox( ) or VanCreateMainForm( ) function. The inbox action type.
$Action
23
The VanPutAttachment( ) function uses the following syntax:
$ret = VanPutAttachment($FormHandle, $Title, $Totallen, $Data, $Length)
A-19
Vanperl Extensions

* *
9 ;
VanPrepareAction $FormHandle
The name of the VanPrepareAction( ) function. An open form handle that was established earlier with the VanCreateInbox( ) or VanCreateMainForm( ) function. The name of the title. The total size of the attachment data. An output variable that receives information on the field when you execute the VanPutAttachment( ) function. The length of the output variable $Data.
$Title $Totallen $Data
$DataLength
%

23
The VanRecordStatus( ) function uses the following syntax:
$ret = VanRecordStatus($FormHandle, [$ModFormHandle])
9 ;
VanRecordStatus $FormHandle
The name of the VanRecordStatus( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. An optional pointer to a buffer that receives the handle of the main form or subform containing modified data.
$ModFormHandle
% 23

The VanSaveRecord( ) function uses the following syntax:
$ret = VanSaveRecord($FormHandle, $vsECode, $vsColumnPath, $Refresh)
A-20
Vanperl Extensions

* *
9 ;
VanSaveRecord $FormHandle
The name of the VanSaveRecord( ) function. An open form handle that was established earlier with the VanCreateMainForm( ) or VanCreateSubForm( ) function. An integer identifying any error condition that occurs. A buffer that receives the column path of the form field or the table column in which the error occurred. A flag that determines if the record is refreshed (reloaded) after a successful save. To reload the record after saving, set this flag to a non-zero value.
$vsECode $vsColumnPath
$Refresh
23
The VanSearchCount( ) function uses the following syntax:
$ret = VanSearchCount($FormHandle)
9 ;
VanSearchCount $FormHandle
The name of the VanSearchCount( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function.
23

The VanSetActionProperty( ) function uses the following syntax:
long VanSetActionProperty($ActionHandle, $ActionProperty, $Data)
A-21
Vanperl Extensions

* *
9 ;
VanSetActionProperty
The name of the VanSetActionProperty( ) function. An identifier for the Action Request to modify. Use the VanSetActionProperty( ) function to create this handle. A valid action property type. This type must be compatible with the kind of action that is modified. An input variable that contains the action request description.
$ActionHandle
$ActionProperty
$Data
" 23

$ret = VanSetField($FormHandle, $ColumnPath, $Data, $vsECode, $vsColumnPath)
The VanSetField( ) function uses the following syntax:
9 ;
VanSetField FormHandle
The name of the VanSetField( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. A path to the column of the field you change with VanSetField( ). An input variable that contains the value to insert in the form field. An integer identifying any error condition that occurs. A buffer that receives the column path of the form field or the table column in which the error occurred.
ColumnPath
Data
$vsECode $vsColumnPath
A-22
Vanperl Extensions

!*
* *
23
The VanStopAction( ) function uses the following syntax:
$ret = VanStopAction($ActionHandle)
9 ;
VanStopAction $ActionHandle
The name of the VanStopAction( ) function. An identifier for the Action Request. Use the VanPrepareAction( ) function to create this handle.
,#
23
The VanUndoChanges( ) function uses the following syntax:
$ret = VanUndoChanges($FormHandle, $UndoAll)
9 ;
VanStopAction $FormHandle
The name of the VanStopAction( ) function. An open form handle that was established earlier with the VanCreateInbox( ), VanCreateMainForm( ), or VanCreateSubForm( ) function. A flag that determines if executing VanUndoChanges( ) undoes changes in subforms.
$UndoAll

The following Vanperl script uses the VanOpenConnection( ) function to establish a connection with a Vantive server host and port. It then uses the VanGetLibInfo( ) function to get library information.
A-23
Vanperl Extensions

!*
* *
If an error condition occurs during the execution of VanOpenConnection( ) or VanGetLibInfo( ), the err_msg subroutine retrieves the error message with the VanGetMsg( ) function.
#!/usr/local/perl5/bin/perl use Vanperl;
sub reportError { local($handle, $str, $status) = @_; local($msg) = '';
printf("Error %s: %ld", $str, $status); VanGetMsg($handle, $msg, 1000); printf("\nMessage: %s\n", $msg); exit(1); }
$dummy = ''; $conn = ''; $status = '';
if (($conn = VanOpenConnection('james', xyz'', 'moon', '1997')) < 0) { reportError(-1, "open connection", $conn); }
if (($status = VanGetLibInfo($conn, VAN_ICLIENT, $dummy, 50)) < 0) { reportError($conn, "GetLibInfo", $status); }
A-24
Vanperl Extensions

!*
* *
printf("client version %s\n", $dummy);
VanCloseConnection($conn, 0, $dummy);
A-25
Vanperl Extensions

!*
* *
A-26
Index

Action receiver 3-20 Action requests 3-4 Action requests 2-1, 2-2,
3-15, 3-19

Bind variables 4-74, 4-77, 4-116 Bind variables 3-10, 3-11, 3-18 Bind variables C3_Data_Types 3-17

Column paths
3-6

Data types Action property 3-21 Action receiver 3-20 Action request 3-19 Bind variables 3-18 Error and warning 3-28 Field description 3-22 Field type values 3-24 Inbox information values 3-25 Subform description values 3-25 XE 3-27 Directory Structure 1-2
For managing action requests 2-2 For managing database cursors 2-5 For managing form fields 2-4 For managing forms and subforms 2-3 For managing info lists 2-7 For managing records 2-6 For retrieving error messages 2-8 For retrieving system versions 2-7 Categories 2-1 Descriptions 4-1 VanAddActionReceiver() 2-3, 4-1 VanAddQualifier() 4-3 VanChildDesc() 2-4, 4-6 VanCloseConnection() 2-2, 4-9 VanCloseCursor() 2-5, 2-6, 4-11 VanCloseDocument() 4-13 VanCloseForm() 2-4, 4-15 VanCreateInboxForm() 2-4, 4-26 VanCreateMainForm() 4-28 VanCreateSubForm() 4-33 VanDoAction() 2-3, 4-41 VanDoResearch() 4-43 VanExtDocLine() 4-45 VanExtDocLineCount() 4-48 VanExtDocLineMaxLength() 4-50 VanExtDocName() 4-53 VanFetchRecord() 2-5, 2-6, 4-55 VanFieldDesc() 2-4, 4-58 VanFreeInfoList() 2-7, 4-61 VanGetDocId() 4-62, 4-64, 4-68, 4-
71, 4-103
VanGetField() 2-5, 4-74 VanGetInfoItem() 2-7, 4-76 VanGetInfoList() 2-7, 4-79 VanGetLibInfo() 2-7, 4-83 VanGetMsg() 2-8, 4-85 VanNewRecord() 2-6, 2-7, 4-87 VanNumChilds() 2-4 VanNumFields() 2-4, 4-91 VanOpenConnection() 2-2, 4-92 VanOpenCursor() 2-5, 4-94 VanOpenExtDocument() 4-97 VanPrepareAction() 2-3, 4-100 VanRecordStatus() 2-7, 4-106

Fields 3-6 Fields 2-4 formatting text elements x Forms Handles 3-3 Functions Categories 2-1 For connecting to server
2-2
VanRestartInfoList() 2-7, 4-108 VanSaveRecord() 2-6, 4-110 VanSearchCound() 4-113 VanSearchCount() 2-5, 2-6 VanSetActionProperty() 2-3, 4-116 VanSetField() 2-4, 2-7, 4-119 VanStopAction() 2-3, 4-122 VanUndoChanges() 2-7, 4-124 VanVanNumChilds() 4-89 Usage VanAddActionReceiver() 3-15, 3-16,
3-19, 3-20, 4-100, 4-117, 4124 VanChildDesc() 3-25 VanCloseConnection() 3-9, 4-92 VanCloseConnections() 3-2 VanCloseCursor() 4-55 VanCreateInboxForm() 3-3, 4-55, 492 VanCreateMainForm() 3-2, 3-3, 4-5, 4-44, 4-55, 4-63, 4-66, 4-69, 4-72, 4-75, 4-89, 4-92, 4-96, 4-104, 4-112, 4-122, 4-126 VanCreateSubForm() 4-55, 4-89 VanDoAction() 3-4, 4-1, 4-41, 4100, 4-117 VanDoResearch() 4-43 VanExtDocLine() 4-50, 4-97 VanExtDocMaxLineLength() 4-46 VanFetchRecord() 4-28, 4-31, 4-33, 4-55, 4-63, 4-66, 4-69, 4-72, 4-75, 4-104, 4-113, 4-125 VanFieldDesc() 3-22, 3-23, 3-24, 491 VanFreeInfoList() 3-5, 4-77, 4-80 VanGetDocId() 4-97 VanGetField() 3-3, 3-7, 3-8, 3-18, 4-28, 4-33, 4-55, 4-63, 4-75 VanGetInfoItem() 3-5, 3-25, 4-80 VanGetInfoList() 3-5, 4-61 VanGetLibInfo() 3-25 VanNewRecord() 4-28, 4-33, 4-87, 4-106, 4-124 VanNumChilds() 4-7
3-2, 3-7, 3-8, 3-9, 4-9, 4-55, 4-83, 4-86 VanOpenCursor() 4-3, 4-11, 4-28, 433, 4-113 VanOpenExtDocument() 4-45, 4-62, 4-97 VanPrepareAction() 3-4, 3-16, 3-19, 3-20, 3-21, 4-1, 4-41, 4-87, 4-116, 4-123 VanRecordStatus() 4-120 VanRestartInfoList() 4-76 VanSaveRecord() 3-13, 3-27, 4-87, 4-125 VanSetActionProperty() 3-18, 3-19, 3-21 VanSetField() 3-13, 3-18, 3-27, 328, 4-28, 4-33, 4-55, 4-106, 4-124
VanOpenConnection()

Handles 3-1 Action request 3-1, 4-1, 4-2 Action requests 3-4 Connection 3-1, 3-2, 4-9, 4-10 Connection 2-2 Form 3-1, 4-5, 4-7, 4-8, 4-10,
4-12,
4-14, A-5 Form and subform 3-3 Form 2-4 Info list 3-2, 3-5

Inboxes 3-4 Info lists 3-5 Handles 3-4, Info lists 2-7 Installation 1-1
3-5

Language elements
3-1
ii

README file on Vantive Media
1-2

Structures 3-7 Using 3-8 Bind variables 3-10 Connection to server 3-8 Managing action receiver information
3-
15
Managing error information Values, input vs output 3-7
3-13

Tables Base 3-6 text elements, formatting
VanFetchRecord() A-12 VanFieldDesc() A-13 VanGetDocId() A-13, A-14 VanGetField() A-15 VanGetLibInfo() A-15 VanGetMsg() A-16 VanNewRecord() A-16 VanNumChilds() A-17 VanNumFields() A-17 VanOpenConnection() A-18 VanOpenCursor() A-18 VanOpenExtDocument() A-19 VanPrepareAction() A-19 VanRecordStatus() A-20 VanSaveRecord() A-20 VanSearchCount() A-21 VanSetActionProperty() A-21 VanSetField() A-22 VanStopAction() A-23 VanUndoChanges() A-23 Variables Bind 4-74, 4-77, Version numbers 2-7
4-116

Vanperl Functions Descriptions VanAddActionReceiver() A-2 VanAddQualifier() A-2 VanChildDesc() A-3 VanCloseConnection() A-4 VanCloseCursor() A-4 VanCloseExtDocument() A-5 VanCloseForm() A-5, A-6, A-7 VanCreateInboxForm() A-7 VanCreateMainForm() A-8 VanCreateRaList() A-8 VanCreateSubForm() A-9 VanDoAction() A-10 VanDoResearch() A-10 VanExtDocLine() A-11 VanExtDocLineCount() A-11 VanExtDocLineMaxLength() A-11 VanExtDocName() A-12
iii

Vantive API: Reference Guide

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Vantive API: Reference Guide

Enviado por

Direitos autorais:

Formatos disponíveis

Vantive API

2 Vantive API Function Categories

3 Vantive API Language Elements

Vantive API Reference Guide

   

  &   3 4                                               *                                                               * &  

  "3 4                                                *!,                                                              *!, &  

&  

                                                             *0+ &  

 3 4                                                    *)                                                             ** &  

   "  /'  

 3 4                                                    7 &

Vantive API Reference Guide

Vantive API Reference Guide

Vantive API Reference Guide

Some or all of the following conventions appear in this guide:

Copy file? Y/N

what the user types the name of a key on the keyboard

...enter RUN.roi in the Application field Press <Enter>.

Vantive API Reference Guide

Important. The bold text following indicates pertinent information.

Information. The bold text following indicates applicable references.

Vantive API Reference Guide

Vantive API Reference Guide

Vantive API supports the following compilers.

Compilers that conform to the Solaris object format:

C Compiler GNU CC Sun C++

Microsoft Visual C++ 4.x Microsoft Visual C++ 5.0

Vantive API Reference Guide

Vantive API Installation

     

vanapi.so vanapi.h example1.c example2.c example3.c

Vantive API Reference Guide

"  #

Vantive API Reference Guide

Vantive API Function Categories

  #     

$# # % &

Vantive API Reference Guide

Vantive API Function Categories

2. Use the VanAddActionReceiver( )function to add

one or more recipients to the recipient list of the Action Request.

4. If necessary, execute the Action Request using the

VanSetActionProperty( ) VanAddActionReceiver( ) VanDoAction( ) VanStopAction( )

Vantive API Reference Guide

Vantive API Function Categories

Vantive API Reference Guide

Vantive API Function Categories

Copies data from a form field to a variable.

VanAddQualifier( ) VanFetchRecord( ) VanCloseCursor( ) VanSearchCount( )

Vantive API Reference Guide

Vantive API Function Categories

VanExtDocLineCount( ) VanExtDocMaxLineLength( ) VanExtDocName( ) VanGetDocId( ) VanExtDocLine( )

$# #% 

Vantive API Reference Guide

Vantive API Function Categories

Vantive API Reference Guide

Vantive API Function Categories

Vantive API Reference Guide

Vantive API Reference Guide

Vantive API Language Elements

A document, which contains information external to your Vantive database

& 3 4 &

"3 4 !, !, &

&

*0+ &

3 4 ) * &

" /'

3 4 7 &

" #

#

$# # % &

$# #%

% &

$# # % '

$# #)-

% &

%