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.

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_NAME];

   CS_INT          lnlen;

   CS_CHAR         first_name[CS_MAX_NAME];

   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). The following table describes the CS_OBJNAME fields:

Table 2-8: 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;

The following table describes the CS_OBJDATA fields:

Table 2-9: 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-8). The following table lists the return code for each combination:

Usage

• 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.

• The following table describes the rules that cs_objects uses to determine whether or not key fields match:

  Table 2-12: 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.

See also

cs_ctx_alloc

---

Copyright © 2003. Sybase Inc. All rights reserved.

View this book as PDF