[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 1

odm_get_obj, odm_get_first, or odm_get_next Subroutine

Purpose

Retrieves objects, one object at a time, from an ODM object class.

Library

Object Data Manager Library (libodm.a)

Syntax

#include <odmi.h>
struct ClassName *odm_get_obj (ClassSymbolCriteriaReturnDataFIRST_NEXT)
struct ClassName *odm_get_first (ClassSymbolCriteriaReturnData)
struct ClassName *odm_get_next (ClassSymbol, ReturnData)
CLASS_SYMBOL ClassSymbol;
char *Criteria;
struct ClassName *ReturnData;
int FIRST_NEXT;

Description

The odm_get_obj, odm_get_first, and odm_get_next subroutines retrieve objects from ODM object classes and return the objects into C language structures defined by the .h file produced by the odmcreate command.

The odm_get_obj, odm_get_first, and odm_get_next subroutines open and close the specified object class if the object class was not previously opened. If the object class was previously opened, the subroutines leave the object class open upon return.

Parameters

ClassSymbol Specifies a class symbol identifier returned from an odm_open_class subroutine. If the odm_open_class subroutine has not been called, then this identifier is the ClassName_CLASS structure that was created by the odmcreate command.
Criteria Specifies the string that contains the qualifying criteria for retrieval of the objects.
ReturnData Specifies the pointer to the data structure in the .h file created by the odmcreate command. The name of the structure in the .h file is ClassName. If the ReturnData parameter is null (ReturnData == null), space is allocated for the parameter and the calling application is responsible for freeing this space at a later time.

If variable length character strings (vchar) are returned, they are referenced by pointers in the ReturnData structure. Calling applications must free each vchar between each call to the odm_get subroutines; otherwise storage will be lost.

FIRST_NEXT Specifies whether to get the first object that matches the criteria or the next object. Valid values are:
ODM_FIRST
Retrieve the first object that matches the search criteria.
ODM_NEXT
Retrieve the next object that matches the search criteria. The Criteria parameter is ignored if the FIRST_NEXT parameter is set to ODM_NEXT.

Return Values

Upon successful completion, a pointer to the retrieved object is returned. If no match is found, null is returned. If an odm_get_obj, odm_get_first, or odm_get_next subroutine is unsuccessful, a value of -1 is returned and the odmerrno variable is set to an error code.

Error Codes

Failure of the odm_get_obj, odm_get_first or odm_get_next subroutine sets the odmerrno variable to one of the following error codes:

ODMI_BAD_CRIT
                          The specified search criteria is incorrectly formed. Make sure the criteria contains only valid descriptor names and the search values are correct.
ODMI_CLASS_DNE
                          The specified object class does not exist. Check path name and permissions.
ODMI_CLASS_PERMS
                          The object class cannot be opened because of the file permissions.
ODMI_INTERNAL_ERR
                          An internal consistency problem occurred. Make sure the object class is valid or contact the person responsible for the system.
ODMI_INVALID_CLXN
                          Either the specified collection is not a valid object class collection or the collection does not contain consistent data.
ODMI_INVALID_PATH
                          The specified path does not exist on the file system. Make sure the path is accessible.
ODMI_MAGICNO_ERR
                          The class symbol does not identify a valid object class.
ODMI_MALLOC_ERR
                          Cannot allocate sufficient storage. Try again later or contact the person responsible for the system.
ODMI_OPEN_ERR
                          Cannot open the object class. Check path name and permissions.
ODMI_TOOMANYCLASSES
                          Too many object classes have been accessed. An application can only access less than 1024 object classes.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The odm_get_list subroutine, odm_open_class subroutine, odm_rm_by_id subroutine, odm_rm_obj subroutine.

The odmcreate command, odmget command.

List of ODM Commands and Subroutines.

For more information about qualifying criteria, see "Understanding ODM Object Searches" in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

See ODM Example Code and Output in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for an example of a .h file.

Object Data Manager (ODM) Overview for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]