Formatting Codes for n_settsql() and n

Formatting Codes for n_settsql() and n_gettsql()

DESCRIPTION
The formatting codes placed in the n_settsql() stmt variable and the n_gettsql() format variable deal with the same kinds of data. Each code's usage for both input and output will be discussed together. The basic difference between input and output modes is as follows.

Output is from n_gettsql() to your variables. All output variables are specified by address (like scanf()) so that they may be re-pointed to the allocated data retrieved from the server. You must free() the output variables when you are finished with the data or your program will grow ever larger with each resultant row until the the bounds of time and space are reached and the universe begins to tear at the seams and finally explodes in a spectacularly fiery ball just because you didn't bother to free a few variables.

Input is from your variables to n_settsql(). Input variables are specified directly (like printf()) rather than by address. They are not modified or freed by n_settsql().

%b

Communicates SQL byte fields via C byte variables. Provide byte ** for output and byte * for input. Typically used for raw binary data. It assumes one byte on input since the length of your data can not be determined. On output it gets as much data as is in the field. It is up to you to know the length of it somehow. See %p%n for more robust buffer handling.

%p%n

Communicates any SQL field type via C byte variables. Provide byte ** and size_t * for output and byte * and size_t for input. Typically used for raw binary data. Both %p and %n must be provided and in that order. Therefore you must supply two variables. The first is a byte pointer to the data buffer and the second is a size_t that is the number of bytes in the buffer.

%s

Communicates SQL char and indirect fields via C char variables. Provide char ** for output and char * for input. The data is a standard '\0' terminated string. Accessing an indirect this way transfers the name of the indirect file. See %< and %> to transfer indirect file contents.

%lf

Communicates SQL double fields via C double variables. Provide double * for output and double for input.

%lu

Communicates SQL date fields via C long variables. Provide long * for output and long for input.

%f

Communicates SQL float fields via C float variables. Provide float * for output and float for input.

%d or %ld

Communicates SQL integer fields via C long variables. Provide long * for output and long for input.

%hd

Communicates SQL smallint fields via C short variables. Provide short * for output and short for input.

%w

Communicates SQL unsigned smallint fields via C word (16 bit) variables. Provide word * for output and word for input.

%dw

Communicates SQL unsigned integer fields via C dword (32 bit) variables. Provide dword * for output and dword for input.

%64d

Communicates SQL int64 fields via C EPI_INT64 (64 bit signed) variables. Provide EPI_INT64 * for output and EPI_INT64 for input. INT64 support was added in Texis version 6.

%64u

Communicates SQL uint64 fields via C EPI_UINT64 (64 bit unsigned) variables. Provide EPI_UINT64 * for output and EPI_UINT64 for input. UINT64 support was added in Texis version 6.

%<

Communicates SQL indirect fields via C char variables and disk files. This is for input only. Provide a char * variable that points to the name of a file. The file will be uploaded to the server and be stored as a Texis managed indirect.

%>

Communicates SQL indirect fields via C char variables and disk files. This is for output only. Provide a char ** variable. The contents of this variable will be examined before retrieving the contents of the indirect file from the server.

In all of the following cases your supplied filename will be replaced with a generated and allocated filename that is where the contents of the indirect file from the server were downloaded to on the local machine. The third case is an exception to the allocated value rule.

If the variable points to (char *)NULL a temporary filename will be generated with the standard C library call tempnam().

If the variable points to the name of an existing directory on the local machine the resulting filename will be that directory with the name of the file on the server appended to it. (i.e. The file will wind up in the specified directory).

Otherwise the variable is taken to be the exact name of the file to place the file from the server in. Anything previously in the specified file will be lost. In this case the resultant filename will be untouched.

The contents of your variable will not be freed, just overwritten. If it needs to be freed, you will have to keep another copy of it to free after the transfer.

%c

Communicates SQL counter fields via C ft_counter variables. Provide a ft_counter ** for output and a ft_counter * for input. ft_counter is a structure that contains two members called date and seq. date is a long that contains the date in seconds (see std. C time()) that the counter was created. seq is a ulong that contains the sequence number for the particular second described by date. The combination of these values provides a unique id across every record in every table in a given database.

%ls

Communicates SQL strlst fields via C char variables. Provide a char *** for output and a char ** for input. The string list is an allocated array of pointers to allocated strings. The list is terminated with an allocated empty string ("").

%aD

Communicates all remaining resultant fields via a C char variable. This is for output only. Provide a char **. All fields that have not already been extracted will be packed together into a C string with the character D between each field. Where D is any single character except \000. Non-printable characters may be specified with octal (\ooo) or hex (\xhh) notation (e.g.: tab would be \011 in octal and \x09 in hex). Binary data that can be converted to human readable form will be (e.g.: INTEGER FLOAT COUNTER). Everything after the %aD code will be ignored since all the fields are now converted.

%o

Communicates Metamorph hit offset information for the preceding field. This is for output only. Provide a MMOFFS **. MMOFFS is the following structure:

MMOFFS             /* Metamorph hit offsets          */
   {
      int n;          /* number if off's in array       */
      MMOFFSE
      {
         long start;  /* byte offset of start of region */
         long end;    /* one past end of region         */
      } *off;         /* array of subhit offset info    */
      int nhits;      /* number of hit's in in array    */
      MMOFFSE *hit;   /* array of hit offset info       */
   };

MMOFFS->off is an array of start and end offsets of subhits (individual search terms) within the field. MMOFFS->n is the number of entries in the off array. Each off is made of two members: long start and long end. Start is the byte offset of the subhit within the field. End is the byte offset of the end of the subhit within the field plus one (plus one makes for() loops easier to write). The offs array contains subhits from all Metamorphs that may have been applied to the field. Offsets are sorted in ascending order by start offset.

Overall hit and delimiter offsets are contained in MMOFFS->hit in a manner analogous to subhit info. MMOFFS->nhits is the number of entries in the hit array and will always be a multiple of three. For each Metamorph on a field there will be three entries. The first contains the offsets of the overall hit (sentence, paragraph, etc...). The second contains the offsets of the start delimiter. The third contains the offsets of the end delimiter.

MMOFFS must be freed with freemmoffs(MMOFFS *) instead of the normal free(void *). freemmoffs(MMOFFS *) can handle MMOFFSPN. This will be MMOFFSPN if there is no Metamorph data for the field. This can happen for a number of reasons. If the search could be completed in the index without needing to read the record, then there will be no hit information. Also if you have ordered the output the hit information can become invalid in the ordering, and the pointer will be NULL.