Chapter 5: C Routines Reference

JagNewCollection

Description

Create a shared-data collection or return a reference to an existing collection.

Syntax

JagStatus JagNewCollection (
            SQLPOINTER name,
            JagLockLevel * pLockLevel,
            JagBoolean * pExists,
            JagDataCollection ** ppCollection)

Parameters

name: The name of the collection.

pLockLevel

Value	To indicate
JAG_LOCKCOLLECTION	Allows locks to be set on collections
JAG_LOCKDATA	Does not allow locks to be set on collections

pExists

is set to one of the following values:

Return value	To indicate
JAG_TRUE	If a collection with the specified name already exists
JAG_FALSE	If a collection with the specified name is created

ppCollection: A pointer to the address of the collection handle.

Returns

Return value	To indicate
JAG_SUCCEED	Success
JAG_FAIL	Failure

Check the server’s log file for more information when JagNewCollection fails.

Usage

The JagNewCollection method:

Creates a new collection with the specified name and lock level, returns a reference to that collection, and sets *pExists to JAG_FALSE, or
Returns a reference to the existing collection with the specified name and sets *pExists to JAG_TRUE. The method’s lock level is ignored and the collection’s current lock level is returned in *pLockLevel.

Collections can be shared only among components that are installed in the same EAServer package. A collection created by a component that is installed in one package can not be retrieved by a component that is installed in a different package.

See Appendix C, “Creating C Components,” in the EAServer Programmer’s Guide for more information.