*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> CSSM_DL_DataGetFirst (3)              



NAME    [Toc]    [Back]

       DL_DataGetFirst,  CSSM_DL_DataGetFirst  -  Get  first data
       record (CDSA)

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/cssm.h>

       API:     CSSM_RETURN     CSSMAPI      CSSM_DL_DataGetFirst
       (CSSM_DL_DB_HANDLE  DLDBHandle,  const  CSSM_QUERY *Query,
       CSSM_HANDLE_PTR                             ResultsHandle,
       CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR              Attributes,
       ResultsHandle,           CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR

LIBRARY    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The  handle  pair  that  describes the add-in data storage
       library module to be used to perform this function and the
       open  data  store  to  search  for  records satisfying the
       query.  The query structure specifying the selection predicate(s)
  used to query the data store. The structure contains
 meta information about the  search  fields  and  the
       relational and conjunctive operators forming the selection
       predicate.  The comparison values to be used in the search
       are specified in the Attributes field of this Query structure.
   If    a    search    attribute    is    of    type
       CSSM_DB_ATTRIBUTE_FORMAT_STRING and the search value specified
 for that string includes a null-terminator, then the
       length  count for that string should include the terminating
 character.  (If null-terminators are used they  should
       be  used  consistently,  storing the terminator as part of
       the string in the data store, otherwise  selection  predicates
  will not locate expected matches.) The Query structure
 attributes also identify the particular attributes to
       be  searched  by this query. If no query is specified, the
       DL module can return the first record in the  data  store,
       performing sequential retrieval, or return an error. If no
       selection predicates are  specified,  the  DL  module  can
       return  the  first  record  in  the data store, performing
       sequential retrieval, or return an  error  (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS).
 When selection predicates are
       specified, the NumberOfValues of  the  Attribute  of  each
       selection predicate must be 1.  If any selection predicate
       does  not  satisfy  this  requirement,  the   error   CSSMERR_DL_INVALID_QUERY
  is returned.  This handle should be
       used to retrieve subsequent records  that  satisfied  this
       query.   If  the  Attributes structure pointer is NULL, no
       values are returned.

              Otherwise, the  DataRecordType,  NumberOfAttributes
              and  AttributeData  fields are read.  AttributeData
              must   be   an    array    of    NumberOfAttributes
              CSSM_DB_RECORD_ATTRIBUTE  elements.  Only  the Info
              field  of  each  element  is  used  on  input.  The
              AttributeFormat  field of the Info field is ignored
              on input.

              On  output,  a  CSSM_DB_RECORD_ATTRIBUTE  structure
              containing a list of all or the requested attribute
              values (subset) from  the  retrieved  record.   The
              SemanticInformation   field   is   set.   For  each
              CSSM_DB_ATTRIBUTE_DATA contained in the  AttributeData
  array,  the  NumberOfValues  field  is set to
              reflect the size of the Value array which is  allocated
  by  the  DL  using the application specified
              allocators.  Each CSSM_DATA in the Value array will
              have it's Data field as a pointer to data allocated
              using the application specified allocators containing
  the attributes value, and have it's Length set
              to the length of the value.

              All values for  an  attribute  are  returned  (this
              could  be  0).  All fields in the Info field of the
              CSSM_DB_ATTRIBUTE_DATA are  left  unchanged  except
              for  the  AttributeFormat  field,  which  is set to
              reflect the schema.  Data values contained  in  the
              referenced memory are ignored during processing and
              are overwritten with the retrieved  opaque  object.
              On  output,  a  CSSM_DATA  structure containing the
              opaque object stored in the retrieved  record.   If
              successful  and  (at least) a record satisfying the
              query has been found, then this parameter returns a
              pointer  to a CSSM_UNIQUE_RECORD_PTR structure containing
 a unique  identifier  associated  with  the
              retrieved record.  This unique identifier structure
              can be used in future  references  to  this  record
              using  this DLDBHandle pairing. It may not be valid
              for other DLHandles targeted to this DL  module  or
              to  other DBHandles targeted to this data store. If
              there are no records  satisfying  the  query,  then
              this  pointer  is  NULL  and CSSM_DL_DataGetFirst()
              must return CSSM_DL_ENDOFDATA; in this case a  normal
   termination   condition   has  occurred.  The
              CSSM_DL_FreeUniqueRecord() must be used to de-allocate
 this structure.

DESCRIPTION    [Toc]    [Back]

       This  function retrieves the first data record in the data
       store that matches the selection criteria.  The  selection
       criteria  (including  selection  predicate  and comparison
       values) is specified in the Query structure. If the  Query
       specifies   an  attribute  that  is  not  defined  in  the
       database's  meta-information,  an   error   condition   is
       returned.  The DL module can use internally-managed indexing
 structures to enhance the performance of the retrieval
       operation. This function selects the first record satisfying
 the query based on the  list  of  Attributes  and  the
       opaque  Data  object. The output buffers for the retrieved
       record are allocated by this  function  using  the  memory
       management  functions  provided  during  the module attach
       operation. This function also returns a results handle  to
       be  used when retrieving subsequent records satisfying the

       Additional  matching  records  are  iteratively  retrieved
       using  the CSSM_DL_DataGetNext() function . The data storage
 module supports one of two retrieval models:  Transactional
 - all query results are determined at initial query
       evaluation. Results do not change  during  an  incremental
       retrieval  process.   File System Scan - query results are
       selected during the incremental retrieval process. Records
       matching  the  query  may  be added to or deleted from the
       underlying data store during the iterative retrieval.  The
       caller  may  receive  the  new  matching  records  and not
       received the deleted records.

       The caller can determine which  retrieval  model  is  supported
  by  examining the encapsulated product description
       for this data storage module.

       If the query selection criteria also  specifies  time  for
       space  limits  for  executing the query, those limits also
       apply ro retrieval of the additional selected data records
       retrieved   using   the   CSSM_DL_DataGetNext()  function.
       Finally, this function returns a unique record  identifier
       associated  with  the retrieved record. This structure can
       be used in future references to the retrieved data record.
       Once  a  user  has finished using a certain query, it must
       call CSSM_DataAbortQuery() for  releasing  resources  that
       CSSM  uses.  If all records satisfying the query have been
       retrieved, then query is automatically terminated.

RETURN VALUE    [Toc]    [Back]

       A CSSM_RETURN value indicating  success  or  specifying  a
       particular  error  condition.  The value CSSM_OK indicates
       success. All other values represent an error condition.

ERRORS    [Toc]    [Back]

       Errors are described in the CDSA technical standard.   See

SEE ALSO    [Toc]    [Back]


       Intel   CDSA   Application    Developer's    Guide    (see

       Reference Pages    [Toc]    [Back]

       Functions for the CSSM API:

       CSSM_DL_DataGetNext(3), CSSM_DL_DataAbortQuery(3)

       Functions for the DL SPI:

       DL_DataGetNext(3), DL_DataAbortQuery(3)

[ Back ]
 Similar pages
Name OS Title
CSSM_DL_DataGetNext Tru64 Get next data record (CDSA)
CSSM_DL_DataGetFromUniqueRecordId Tru64 Get data record (CDSA)
DL_DataGetFromUniqueRecordId Tru64 Get data record (CDSA)
DL_DataGetNext Tru64 Get next data record (CDSA)
CSSM_DL_DataDelete Tru64 Remove data record (CDSA)
DL_DataDelete Tru64 Remove data record (CDSA)
DL_DataInsert Tru64 Create new persistent data record (CDSA)
DL_DataModify Tru64 Modify persistent data record (CDSA)
CSSM_DL_DataInsert Tru64 Create new persistent data record (CDSA)
CSSM_DL_DataModify Tru64 Modify persistent data record (CDSA)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service