FairCom ISAM for C

ctfiltercb_rowl

Provides a callback evaluation function for system-wide filters.

Declaration

The function ctfiltercb_rowl() is located in ctclbk.c and has the following prototype:

NINT ctfiltercb_rowl(pTEXT Clbk, pVOID recptr, pConvMap Schema, VRLEN fixlen, VRLEN datlen, pTEXT username, pTEXT nodename, pVOID oldptr, VRLEN oldlen, LONG opcode pinHan);

Description

Clbk points to a nul terminated ASCII string beginning with two ctCNDXclbkCHR ('@') characters and a third character, '?' or '!', that designates a read or write filter, respectively. The string starting in the 4th position (i.e., Cblk + 3) points to a callback function designator, which is the table name.

recptr points to a record buffer image.

Schema points to a record schema. If you wish to use the record schema, then add the following local variable:

pConvBlk cp = (pConvBlk) (schema + 1);

cp now points to array of individual field descriptors.

fixlen indicates the fixed record length of the record buffer image.

datlen indicates the full length of the record buffer image. datlen may be greater than fixlen for variable length records.

oldptr points to an old record image. oldlen is the length of the old record image pointed by oldptr. Old record images are necessary for deletes so that the system filter can check whether delete permission exists based on user attributes and field values. For rewrites, the case is similar and more interesting: imagine that a user has permission to read a record and to put the contents of the new image in the record, but does not have permission to get rid of one or more of the old field values. Even though the user has permission for the new values that are replacing the old field values, they are not authorized to change the old values. Therefore a rewrite needs both the old and new images.

opcode is one of the following:

opcode	Explanation
ctROWL_READ	Called from a record read
ctROWL_WRITE	Called from a low level record write
ctROWL_ADDREC	Called from an ISAM add record
ctROWL_DELREC	Called from an ISAM delete record
ctROWL_RWTREC	Called from an ISAM rewrite

pinHan is a macro used internally by c-tree Plus code.

On a read, if the permanent read filter does not pass the record, then it behaves just as with the temporary, user-specific read filters: a low-level read would return error FFLT_ERR (739) and an ISAM-level read will skip the record. On a write, a record that does not pass the permanent write filter will cause the write to fail with error SWRT_ERR (458).

Function ctfiltercb_rowl() returns errors as a negative value, 0 if the record does NOT match the filter, or > 0 if the record passes the filter.

Note: To provide extended debug information with this function, define ctDBGcb_rowl when cttseg.c is compiled, and all record images passed to the call back routine will be annotated and hex-dumped into an output file, TestRowl.FCS.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.
458	SWRT_ERR	Write permission not granted.
739	FFLT_ERR	Record does not pass filter.

See Appendix A for a complete listing of valid c-tree Plus error values.

ctfiltercb_rowl Callback Example