GpiQuerySegmentNames

This function returns the identifiers of all segments that exist with identifiers in a specified range.

Syntax

GpiQuerySegmentNames(hps, lFirstSegid, lLastSegid, lMax, alSegids)

Parameters

hps (HPS) - input: Presentation-space handle.

lFirstSegid (LONG) - input: First segment in the range (must be greater than 0).

lLastSegid (LONG) - input: Last segment in the range (must be greater than 0).

lMax (LONG) - input: Maximum number.; This is the maximum number of segment identifiers to be returned in alSegids.

alSegids (PLONG) - output: Array in which the required identifiers are returned.

Return Value

lRetCount (LONG) - returns

Number of identifiers returned.

>=0: Number of identifiers returned
GPI_ALTERROR: Error.

Remarks

Nonretained segment identifiers are not returned. If lFirstSegid is the same as, or greater than lLastSegid, the search terminates after querying only the segment with lFirstSegid.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_SEG_NAME (0x20C8): An invalid segment identifier was specified.
PMERR_INV_LENGTH_OR_COUNT (0x2092): An invalid length or count parameter was specified.
PMERR_INV_MICROPS_FUNCTION (0x20A1): An attempt was made to issue a function that is invalid in a micro presentation space.

Example Code

#define INCL_GPISEGMENTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS   hps;         /* Presentation-space handle. */
LONG  lFirstSegid; /* First segment in the range (must be greater than 0). */
LONG  lLastSegid;  /* Last segment in the range (must be greater than 0). */
LONG  lMax;        /* Maximum number. */
PLONG alSegids;    /* Array in which the required identifiers are returned. */
LONG  lRetCount;   /* Number of identifiers returned. */

lRetCount = GpiQuerySegmentNames(hps, lFirstSegid, lLastSegid, lMax, alSegids);

This function returns the identifiers of all segments that exist within a specified range.

#define INCL_GPISEGMENTS
#include <OS2.H>

#define Maxsegs 5

LONG lRetCount;
HPS hps; /* Presentation-space */
/* handle. */
LONG lFirstSegid; /* First segment in the */
/* range (must be greater */
/* than 0). */
LONG lLastSegid; /* Last segment in the */
/* range (must be greater */
/* than 0). */
LONG lMax; /* This is the maximum */
/* number of segment */
/* identifiers to be returned */
/* in alSegids. */
LONG alSegids[Maxsegs]; /* Array in which the */
/* required identifiers are */
/* returned. */

lFirstSegid = 1;
lLastSegid = Maxsegs;
lMax = Maxsegs;

lRetCount = GpiQuerySegmentNames(hps,
    lFirstSegid,
    lLastSegid,
    lMax,
    alSegids);

Related Functions