Technical Reference: Base Operating System and Extensions, Volume 1

odm_get_list Subroutine

Purpose

Retrieves all objects in an object class that match the specified criteria.

Library

Object Data Manager Library (libodm.a)

Syntax

#include <odmi.h>

struct ClassName *odm_get_list (ClassSymbol, Criteria, ListInfo, MaxReturn, LinkDepth)
struct ClassName_CLASS ClassSymbol;
char * Criteria;
struct listinfo * ListInfo;
int MaxReturn, LinkDepth;

Description

The odm_get_list subroutine takes an object class and criteria as input, and returns a list of objects that satisfy the input criteria. The subroutine opens and closes the object class around the subroutine if the object class was not previously opened. If the object class was previously opened, the subroutine leaves the object class open when it returns.

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 is the ClassName_CLASS structure created by the odmcreate command.
Criteria	Specifies a string that contains the qualifying criteria for selecting the objects to remove.
ListInfo	Specifies a structure containing information about the retrieval of the objects. The listinfo structure has the following form: struct listinfo { char ClassName[16]; /* class name used for query / char criteria[256]; / query criteria / int num; / number of matches found / int valid; / for ODM use / CLASS_SYMBOL class; / symbol for queried class */ };
MaxReturn	Specifies the expected number of objects to be returned. This is used to control the increments in which storage for structures is allocated, to reduce the realloc subroutine copy overhead.
LinkDepth	Specifies the number of levels to recurse for objects with ODM_LINK descriptors. A setting of 1 indicates only the top level is retrieved; 2 indicates ODM_LINKs will be followed from the top/first level only: 3 indicates ODM_LINKs will be followed at the first and second level, and so on.

Return Values

Upon successful completion, a pointer to an array of C language structures containing the objects is returned. This structure matches that described in the .h file that is returned from the odmcreate command. If no match is found, null is returned. If the odm_get_list subroutine fails, a value of -1 is returned and the odmerrno variable is set to an error code.

Error Codes

Failure of the odm_get_list subroutine sets the odmerrno variable to one of the following error codes:

See Appendix B. ODM Error Codes in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 1 for explanations of the ODM error codes.

Related Information

The odm_get_by_id (odm_get_by_id Subroutine) subroutine, odm_get_obj (odm_get_obj, odm_get_first, or odm_get_next Subroutine) subroutine, odm_open_class (odm_open_class Subroutine) subroutine, or odm_free_list (odm_free_list Subroutine) subroutine.

The odmcreate command, odmget command.

List of ODM Commands and Subroutines.

For information on qualifying criteria, see "Understanding ODM Object Searches" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

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

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