Old Listing

The API of the deprecated (legacy) Listing. More...

Classes
struct	API_ListDataSetType
	Representation of a listdata set. More...
struct	API_ListData_Head
	Contains common information related to all listing component types. More...
struct	API_KeyType
	Description of a key. More...
struct	API_UnitType
	Description of an unit. More...
struct	API_Obsolete_ComponentType
	Description of a component. More...
struct	API_DescriptorType
	Description of a descriptor. More...
union	API_ListData
	The representation of a listdata. More...

Enumerations
enum	API_ListDataID {   API_ZombieListDataID , API_KeyID , API_UnitID , API_Obsolete_ComponentID ,   API_DescriptorID }
	Possible types of a listdata item. More...

Functions
Int32	ACAPI_OldListing_GetSetNum (void)
	Returns the number of listdata sets.
GSErrCode	ACAPI_OldListing_GetSet (API_ListDataSetType *listdataSet)
	Retrieves the data of a listdata set.
GSErrCode	ACAPI_OldListing_GetNum (Int32 setIndex, API_ListDataID typeID, Int32 *count)
	Returns the number of listdata in given set.
GSErrCode	ACAPI_OldListing_Get (API_ListData *listdata)
	Retrieves the data of a listdata.
GSErrCode	ACAPI_OldListing_Search (API_ListData *listdata)
	Searches for a listdata.
GSErrCode	ACAPI_OldListing_GetLocal (Int32 libIndex, const API_Elem_Head *elemHead, API_ListData *listdata)
	Retrieves the data of a local listing component.

Detailed Description

The API of the deprecated (legacy) Listing.

Enumeration Type Documentation

API_ListDataID

enum API_ListDataID

Possible types of a listdata item.

Remarks

This enum is used when you get information about the listing database or use API_ListData. See the ACAPI_OldListing_Get, ACAPI_OldListing_GetLocal, ACAPI_OldListing_Search, ACAPI_OldListing_GetNum functions.

Function Documentation

ACAPI_OldListing_Get()

GSErrCode ACAPI_OldListing_Get

(

API_ListData *

listdata

)

Retrieves the data of a listdata.

Parameters

listdata

[in/out] Parameters of the listdata. The type of the listdata, the index of the set and the index of the listdata must be passed in the typeID, the setIndex and the index fields in the listdata header. Other fields of the structure are filled in automatically.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - Invalid listdata index was passed.
• APIERR_BADID - Invalid listdata type was passed.
• APIERR_DELETED - Invalid listdata was deleted.

Remarks

This function is used to get a listdata, defined by the typeID, the setIndex and the index fields of the listdata header. The information of a given listdata is returned in the fields of the listdata. This function is faster than ACAPI_OldListing_GetLocal. When getting the listdata, the applicable fields should be filled in.

API_ListData_Head
setIndex	required; must be >= 1
typeID	required
index	required

If you are retrieving a descriptor, don't forget to dispose of the name handle when you're finished.

Example

API_ListData  listdata;
GSErrCode     err;
 
BNZeroMemory (&listdata, sizeof (API_ListData));
listdata.header.setIndex = 1;
listdata.header.typeID   = API_DescriptorID;
listdata.header.index    = 1;
 
err = ACAPI_OldListing_Get (&listdata);
 
BMKillHandle (&listdata.descriptor.name);

ACAPI_OldListing_GetLocal()

GSErrCode ACAPI_OldListing_GetLocal	(	Int32	libIndex,
		const API_Elem_Head *	elemHead,
		API_ListData *	listdata
	)

Retrieves the data of a local listing component.

Parameters

libIndex	[in] Index of the library part.
elemHead	[in] Element of the placed object instance (see remarks).
listdata	[in/out] Parameters of the listdata. The type of the listdata must be passed in the typeID field in the listdata header. The index in the library part must be passed in the index field in the listdata header. The other fields of the structure are filled in automatically.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Invalid libIndex was passed.
• APIERR_BADID - Invalid listdata type was passed.

Remarks

This function is used to get a local component or descriptor in the library part defined by libIndex and typeID, the index field of the listdata header. The information of a given listdata is returned in the fields of the listdata. If the given listdata is in the listing database, use the ACAPI_OldListing_Get function instead. When getting the local listdata, the applicable fields should be filled.

API_ListData_Head
index	required
typeID (only for API_Obsolete_ComponentID and API_DescriptorID)	required
libIndex	required

If you are retrieving a descriptor, do not forget to dispose of the name handle when you're finished. If the listing result depends on the current settings of the library part parameters (which is possible when the component or descriptor definitions in the property script of the object refer to GDL parameters of the object), you might need to get the correct data to be listed for a placed element. In this case you need to pass the appropriate elemTypeID and elemIndex parameters. Otherwise these values should be API_ZombieElemID and 0 respectively.

Example

API_LibPart   libPart;
API_ListData  listdata;
API_Elem_Head head;
Int32         libIndex;
GSErrCode     err;
 
BNZeroMemory (&libPart, sizeof (API_LibPart));
BNZeroMemory (&head, sizeof (API_Elem_Head));
 
libPart.typeID = APILib_PropertyID;
GS::ucscpy (libPart.docu_UName, L("Test property"));
 
err = ACAPI_LibraryPart_Search (&libPart, false);
delete libPart.location;
 
if (err == NoError && libPart.index != 0) {
    libIndex = libPart.index;
 
    BNZeroMemory (&listdata, sizeof (API_ListData));
    listdata.header.typeID = API_Obsolete_ComponentID;
    listdata.header.index  = 1;
 
    err = ACAPI_OldListing_GetLocal (libIndex, &head, &listdata);
}

ACAPI_OldListing_GetNum()

GSErrCode ACAPI_OldListing_GetNum	(	Int32	setIndex,
		API_ListDataID	typeID,
		Int32 *	count
	)

Returns the number of listdata in given set.

Parameters

setIndex	[in] Index of the sets of the listing database.
typeID	[in] Type of the listdata.
count	[out] Number of listdata type in the set.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Invalid listdata type or setIndex was passed.

Remarks

This function is used to get the highest available listdata index of the given listdata type in the set.

Example

/* How many keys are in the first database set? */
 
Int32   count;
err = ACAPI_OldListing_GetNum (1, API_KeyID, &count);

ACAPI_OldListing_GetSet()

GSErrCode ACAPI_OldListing_GetSet

(

API_ListDataSetType *

listdataSet

)

Retrieves the data of a listdata set.

Parameters

listdataSet

[in/out] Parameters of the set. The index of the set must be passed in the setIndex field in the listdataSet; it must be greater than 0. The other fields of the structure are filled in automatically.

Returns

• NoError - The function has completed with success.
• APIERR_BADINDEX - Invalid listdataSet setindex was passed.

Remarks

This function is used to get a listdata set, defined by the setIndex field of the listdataSet. The information of a given listdata set is returned in the fields of the listdataSet. When getting the listdata set, the applicable fields should be filled: the API_ListDataSetType setIndex is required.

Example

API_ListDataSetType  listdataSet;
GSErrCode            err;
 
BNZeroMemory (&listdataSet, sizeof (API_ListDataSetType));
listdataSet.setIndex = 1;
 
err = ACAPI_OldListing_GetSet (&listdataSet);

ACAPI_OldListing_GetSetNum()

Int32 ACAPI_OldListing_GetSetNum

(

void

)

Returns the number of listdata sets.

Returns

• NoError - The number of listdata sets of the listing database.

Remarks

This function is used to get number of sets of the listing database.

Example

Int32   count = ACAPI_OldListing_GetSetNum ();

ACAPI_OldListing_Search()

GSErrCode ACAPI_OldListing_Search

(

API_ListData *

listdata

)

Searches for a listdata.

Parameters

listdata

[in/out] Parameters of the listdata. The type and setIndex of the listdata must be passed in the typeID and the setIndex fields in the listdata header. The code and/or the keycode of the listdata must be passed in the code and the keycode fields in the listdata. The setIndex and the index fields of the listdata header are used as the output parameters to return the setIndex/index to the searched listdata.

Returns

• NoError - The function has completed with success.
• APIERR_BADKEYCODE - Invalid code or keycode was passed.

Remarks

This function is used to search for a listdata, identified by the setIndex, the typeID and the code/keycode fields in the listdata header. Units and keys are searchable by code, components and descriptors are searchable by code and/or keycode. The All sets of listing database are sorted by keycode.

API_ListData_Head
setIndex	required (if it's 0 - search in all sets)
typeID	required

API_ListDataID	keycode	code
API_KeyID or API_UnitID	not exist	required
API_Obsolete_ComponentID or API_DescriptorID	required	optional

Example

API_ListData  listdata;
char          buffer[256];
GSErrCode     err;
 
BNZeroMemory (&listdata, sizeof (API_ListData));
 
listdata.header.setIndex = 0;
listdata.header.typeID   = API_Obsolete_ComponentID;
CHCopyC ("003", listdata.component.keycode);
CHCopyC ("", listdata.component.code);
 
err = ACAPI_OldListing_Search (&listdata);
if (err == NoError) {
    sprintf (buffer, "Set index: %d,  key code: \"003\"", listdata.header.setIndex);
    ACAPI_WriteReport (buffer, false);
 
    err = ACAPI_OldListing_Get (&listdata);
    while (err == NoError && CHEqualASCII (listdata.component.keycode, "003", GS::CaseInsensitive)) {
        sprintf (buffer, " Code: \"%s\", name: %s", listdata.component.code, listdata.component.name);
        ACAPI_WriteReport (buffer, false);
 
        listdata.header.index++;
        err = ACAPI_OldListing_Get (&listdata);
    }
}