cs_objects

Description

Saves, retrieves, or clears objects and data associated with them.

Syntax

CS_RETCODE cs_objects(context, action, objname,
                objdata)
 
 CS_CONTEXT       *context;
 CS_INT                  action;
 CS_OBJNAME       *objname;
 CS_OBJDATA         *objdata;

Parameters

context: A pointer to a CS_CONTEXT structure.

action: One of the following symbolic values:

Value of action

cs_objects

CS_SET

Saves an object.

CS_GET

Retrieves the first matching object that it finds.

CS_CLEAR

Clears all matching objects.

Value of action	cs_objects
CS_SET	Saves an object.
CS_GET	Retrieves the first matching object that it finds.
CS_CLEAR	Clears all matching objects.

objname

A pointer to an object name structure. *objname names and describes the object of interest. An object name structure is defined as follows:

/*

 ** CS_OBJNAME

*/

 typedef struct _cs_objname

   CS_BOOL         thinkexists;

   CS_INT          object_type;

   CS_CHAR         last_name[CS_MAX_CHAR];

   CS_INT          lnlen;

   CS_CHAR         first_name[CS_MAX_CHAR];

   CS_INT          fnlen;

   CS_VOID         *scope;

   CS_INT          scopelen;

   CS_VOID         *thread;

   CS_INT          threadlen;

 } CS_OBJNAME;

The object_type, last_name, first_name, scope, and thread fields form a five-part key that identifies a stored object (see “cs_objects naming keys” for more information). Table 2-9 describes the CS_OBJNAME fields:

**Table 2-9: CS_OBJNAME fields**
Field	Description	Notes
thinkexists	Indicates whether the application expects this object to exist.	The value of thinkexists affects the cs_objects return code. For more information, see the Return values.
object_type	The type of the object.	This field is the first part of a five-part key. object_type can be one of these values: CS_CONNECTNAME CS_CURSORNAME CS_STATEMENTNAME CS_CURRENT_CONNECTION CS_WILDCARD (matches any value) A user-defined value. User-defined values must be >= 100.
last_name	The “last name” associated with the object of interest, if any.	This field is the second part of a five-part key.
lnlen	The length, in bytes, of last_name.	Can be CS_NULLTERM to indicate a null-terminated last_name. Can be CS_UNUSED to indicate an internal “unused” value for last_name. For CS_GET and CS_CLEAR operations, can be CS_WILDCARD to match any last_name value.
first_name	The “first name” associated with the object of interest, if any.	This field is the third part of a five-part key.
fnlen	The length, in bytes, of first_name.	Can be CS_NULLTERM to indicate a null-terminated first_name. Can be CS_UNUSED to indicate an internal “unused” value for first_name. For CS_GET and CS_CLEAR operations, can be CS_WILDCARD to match any first_name value.
scope	Data that describes the scope of the object.	This field is the fourth part of a five-part key.
scopelen	The length, in bytes, of scope.	Can be CS_NULLTERM to indicate null-terminated scope data. Can be CS_UNUSED to indicate an internal “unused” value for scope. For CS_GET and CS_CLEAR operations, can be CS_WILDCARD to match any scope* value.
thread	Platform-specific data that is used to distinguish threads in a multi-threaded execution environment.	This field is the fifth part of a five-part key.
threadlen	The length, in bytes, of thread.	Can be CS_NULLTERM to indicate null-terminated thread data. Can be CS_UNUSED to indicate an internal “unused” value for thread. For CS_GET and CS_CLEAR operations, can be CS_WILDCARD to match any thread* value.

objdata

A pointer to an object data structure. *objdata is the object of interest and any data associated with it. An object data structure is defined as follows:

/*

 ** CS_OBJDATA

*/

 typedef struct _cs_objdata

   CS_BOOL           actuallyexists;

   CS_CONNECTION     *connection;

   CS_COMMAND        *command;

   CS_VOID           *buffer;

   CS_INT            buflen;

 } CS_NAMEDATA;

Table 2-10 describes the CS_OBJDATA fields:

**Table 2-10: CS_OBJDATA fields**
Field	Description	Notes
actuallyexists	Indicates whether this object actually exists.	cs_objects sets actuallyexists to CS_TRUE if it finds a matching object. cs_objects sets actuallyexists to CS_FALSE if it does not find a matching object.
connection	A pointer to the CS_CONNECTION structure representing the connection in which the object exists.
command	A pointer to the CS_COMMAND structure representing the command space with which the object is associated.	Can be NULL.
buffer	A pointer to data space. An application can use buffer to associate data with a saved object.	If action is CS_SET, *buffer contains the data to associate with the object. If action is CS_GET, cs_objects sets *buffer to the data associated with the object being retrieved.
buflen	The length, in bytes, of *buffer.	If action is CS_SET, buflen is the length of the data contained in *buffer. Can be CS_NULLTERM to indicate null-terminated data. Can be CS_UNUSED to indicate that there is no data associated with the object being saved. If action is CS_GET, buflen is the maximum capacity of *buffer. cs_objects overwrites buflen with the number of bytes copied to *buffer. If buflen is CS_UNUSED, cs_objects overwrites buflen with the length of the data but does not copy it to *buffer.

Returns

cs_objects returns CS_SUCCEED or CS_FAIL depending on the values passed as action and objname−>thinkexists (See Table 2-9). Table 2-11 lists the return code for each combination:

**Table 2-11: cs_objects return values**
cs_objects Called with		cs_objects returns
action As	objname→thinkexists As	No match	Last-name match	Full match
CS_GET	CS_TRUE	CS_FAIL	CS_FAIL	CS_SUCCEED
CS_GET	CS_FALSE	CS_SUCCEED	CS_SUCCEED	CS_SUCCEED
CS_SET	CS_TRUE	CS_FAIL	CS_FAIL	CS_SUCCEED
CS_SET	CS_FALSE	CS_SUCCEED	CS_SUCCEED	CS_FAIL
CS_CLEAR	CS_TRUE	CS_FAIL	CS_FAIL	CS_SUCCEED
CS_CLEAR	CS_FALSE	CS_SUCCEED	CS_SUCCEED	CS_SUCCEED

Usage

**Table 2-12: Summary of cs_objects parameter usage**
Value of action	objname is	objdata is
CS_SET	A five-part key for the object.	The object to save and any additional data to save with it.
CS_GET	A five-part key for the object.	Set to the retrieved object.
CS_CLEAR	A five-part key for the object.	CS_UNUSED.

cs_objects is useful in precompiler applications that need to retrieve structures and data items by name.

cs_objects naming keys

cs_objects uses a five-part key, composed of the object_type, last_name, first_name, scope, and thread fields of *objname structure.

On CS_SET operations, cs_objects uses this key to store the *objdata object.
On CS_GET operations, cs_objects uses this key to retrieve an object specification into *objdata.
On CS_CLEAR operations, cs_objects clears all objects that match the key.

Table 2-13 describes the rules that cs_objects uses to determine whether or not key fields match:

**Table 2-13: cs_objects key matching rules**
*objname key length is	Stored key length is CS_UNUSED	Stored key length is another legal value
CS_WILDCARD	Match	Match
CS_UNUSED	Match	No match
Another Legal Value	No match	Match, if the names match and have the same length.

cs_objects can achieve two types of matches:

“last-name matches,” in which the last_name, scope, and thread parts of the key match.
“full matches,” in which all five parts of the key match.

The type of match that cs_objects achieves, together with action and objname−>thinkexists, determine its return code.

On CS_GET and CS_CLEAR operations, an application may specify CS_WILDCARD for one or more *objname key fields:

On a CS_GET operation, cs_objects sets *objdata to reflect the first matching object that it finds.
On a CS_CLEAR operation, cs_objects clears all matching objects.

Retrieving “Current Connection” objects

If an application has previously saved a CS_CURRENT_CONNECTION object, it can retrieve the current connection by:
- Calling cs_objects with objname−>object_type as CS_CURRENT_CONNECTION, lnlen as CS_UNUSED, and fnlen as CS_UNUSED. cs_objects ignores the last_name and first_name fields of objname, and sets objdata−>buffer to the name of the current connection and objdata−>buflen to the length of this name.
- Calling cs_objects with objname−>object_type as CS_CONNECTNAMEand objname−>last_name and objname−>lnlen as the newly retrieved connection name and name length. cs_objects sets objdata to the retrieved connection.

WARNING! An application cannot call cs_objects(CS_SET) from within a completion callback routine.