Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

GetCtResource

Get Resource record from data file.

Short Name

GETRES()

Type

Low-Level data file resource function

Declaration

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

VRLEN bufsiz, COUNT resmode)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

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. FairCom DB 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 with the record address for non-huge files. If the target file is a huge file, resptr points to an array of 2 LONG values with the first holding the high word and the second holding the low word of 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.

See also Record Offsets Under Huge File Support.

Return

If no error occurs, GetCtResource() returns the byte offset for the Resource record. On RBUF_ERR (404), GetCtResource() returns the resource offset 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 FairCom DB Error Codes for a complete listing of valid FairCom DB 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; /* FairCom DB 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; /* FairCom DB 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);

See also

LockCtData(), LockISAM(), ctSETHGH(), ctGETHGH(), UpdateCtResource(), AddCtResource(), DeleteCtResource()

TOCIndex