GetCtResource

Get Resource record from data file.

Short Name

GETRES()

Type

Low-level data file resource function

Declaration

LONG GetCtResource(COUNT datno, pVOID resptr, pVOID bufptr,

                   VRLEN bufsiz, COUNT resmode)

Description

GetCtResource() retrieves a Resource from data file datno, returns a long integer corresponding to the byte offset of the Resource, and places the value of the Resource in the buffer pointed to by bufptr. bufsiz is the size of the buffer area. The buffer will contain the entire Resource Data Block. See AddCtResource() for information.

resmode specifies the method of searching for the Resource. resptr points to the identifying information used in the search. The resmode choices are:

RES_FIRST	Find the Resource with the lowest available Type and Number. resptr is not used.
RES_LENGTH	This mode must be OR-ed with a retrieval mode such as RES_POS, RES_FIRST, or RES_NAME. Returns three 4-byte integers: resource type, resource number, and resource length.
RES_LOCK	Asks for a low-level exclusive lock on the matching Resource record. This lock is released by UpdateCtResource() or DeleteCtResource(), or with LockCtData(). Resource locks are NOT released by LockISAM().
RES_NAME	Finds the first Resource with a matching name. c-tree Plus cannot guarantee unique resource names. resptr points to a buffer containing the target name for the search.
RES_NEXT	Retrieves the next physical resource from the specified datno. Seed this mode with a resource type and resource number to receive the next greater resource.
RES_POS	Read the Resource at the record address obtained in a prior call to GetCtResource(). resptr points to a long integer with the record address.
RES_Type	Find the Resource with the matching type and lowest available number. resptr points to the resource type.
RES_TYPNUM	Finds the Resource with the matching type and number. resptr points to a resource type followed by a resource number.

Return

If no error occurs, GetCtResource() returns the byte offset for the Resource record. On RBUF_ERR (404), GetCtResource() returns the required buffer size and sets uerr_cod to 404. Otherwise, GetCtResource() returns a zero and uerr_cod is set as follows:

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful operation.
42	DLOK_ERR	A lock cannot be placed on this record with RES_LOCK.
48	FMOD_ERR	datno does not have Resources enabled.
401	RNON_ERR	datno does not have Resources enabled.
403	RZRO_ERR	Empty resource ID.
404	RBUF_ERR	bufsiz is smaller than the resource found. (The return value is the resource offset in this case.) Use the the RES_LENGTH resmode to retrieve the necessary buffer size.
406	RCSE_ERR	Invalid resmode value.
407	RRED_ERR	Attempt to get non-resource info. The byte offset provided with RES_POS mode does not point to a valid resource record.
408	RNOT_ERR	Resource not found. No resource is found that matches the values specified by resmode.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example: 1 RES_NAME

struct {                    /* Resource Data Block structure */

    ULONG     resource_type;

    ULONG     resource_number;

    TEXT      variable_info[1016]; /* This holds the         */

} my_resource;                     /* Resource Name and Data */


my_resource.resource_type    = 0x10001L;            /* 65537 */

my_resource.resource_number  = 0xffffffffL;         /* c-tree Plus assigns number*/


strcpy(my_resource.variable_info,"MY!resource");

strcpy(my_resource.variable_info+12,"Actual Resource Data");


if (AddCtResource(datno,&my_resource,

   (VRLEN)(8 + 12 + strlen(my_resource.variable_info+12))) == 0)

    printf("\nThe resource has been assigned number %ld",

           my_resource.resource_number);

    printf("\nThe resource is located at byte offset %ld.",

           GetCtResource(datno, "MY!resource", &my_resource,

                         1024L, RES_NAME));

} else

    printf("\nCould not add resource. Error #%d",uerr_cod);

Example 2: RES_LENGTH

struct {

    ULONG     resource_type;

    ULONG     resource_number;

    TEXT      variable_info[504];

} sample;


LONG     ret;          /* length returned from GetCtResource */


sample.resource_type = 0x10001L;                    /* 65537 */

sample.resource_number = 0xffffffffL;               /* c-tree Plus assigned number  */

strcpy(sample.variable_info,"SAMPLE1!resource");    /* assign resource name */

strcpy(sample.variable_info+18,

       "This is the first resource record.");


if (AddCtResource(datno, &sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding first resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of first Resource Record");


strcpy(sample.variable_info,"SAMPLE2!resource");

                                     /* assign resource name */

strcpy(sample.variable_info+18,

       "This is the second resource record.");


if (AddCtResource(datno,&sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding second resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of second Resource Record");


strcpy(sample.variable_info,"SAMPLE3!resource");

 /* assign resource name */         strcpy(sample.variable_info+18,

       "This is the third resource record.");


if (AddCtResource(datno, &sample,

    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)

    printf("\nError adding third resource!, error = %d", uerr_cod);

else

    printf("\nSuccessful addition of third Resource Record");


if ((ret=GetCtResource(datno, "SAMPLE1!resource", &sample, 512,

                       RES_NAME | RES_LENGTH)) != 0)

    cpybuf(&ret,sample.variable_info, sizeof(LONG));

    printf("\nFirst resource name is %ld bytes long",ret);

else

    printf("\n\nError on First resource length = %d",uerr_cod);

Example 3: RES_NEXT

    if ((ret = GetCtResource(datno, "SAMPLE1!resource", &sample,

                         512, RES_NAME)) !=0)

    printf("\nFirst resource is %s",sample.variable_info);

else

    printf("\n\nError on First resource = %d",uerr_cod);


if ((ret = GetCtResource(datno, &sample, &sample, 512, RES_NEXT)) !=0)

    printf("\nNext resource is %s",sample.variable_info);

else

    printf("\n\nError on Next resource = %d",uerr_cod);