FairCom ISAM for C

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.

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);