Initializing help system before first use

Introduction

Topics covered in this chapter:

The BinDrv library provides the necessary routines to generate and parse data streams using a structured binary and platform independent format. This data format may be employed to generate data files that have to be exchanged between platforms with different byte ordering (or endianness). This is also the file format used by the "bin:" Mosel I/O driver such, that this library enables an application to create (and read) binary data files to be used by Mosel models.

Generating a data file

To generate a data file, a bindrv writer context has to be allocated with a call to bindrv_newwriter. This initialisation routine requires a callback function that is used for outputing data to some stream (e.g. use the C function fwrite to write to a file opened with the function fopen). Then, each data value to be saved to the stream is passed to the function corresponding to its type: this routine builds a token equivalent to the provided object and sends it to the stream. For instance, function bindrv_putint will be used to output an integer etc.. In order to structure the data flow, special markers may be inserted: the function bindrv_putctrl allows to add these control tokens. A control token is characterised by its code (an integer between 0 and 31) such that different types of markers can be used. For instance, control code 1 could indicate the beginning of a list of integers, code 4 the beginning of a list of text strings, code 2 for the end of a list and code 3 could be used to mark the end of the data flow. Using this convention, a file containing a list of integers (e.g. 5,6,7) and a list of strings (e.g. "a","b") could be produced with the following code:

bindrv_putctrl(bctx,1);
bindrv_putint(bctx,5);
bindrv_putint(bctx,6);
bindrv_putint(bctx,7);
bindrv_putctrl(bctx,2);
bindrv_putctrl(bctx,4);
bindrv_putstring(bctx,"a");
bindrv_putstring(bctx,"b");
bindrv_putctrl(bctx,2);
bindrv_putctrl(bctx,3);

Parsing a data file

To parse a data file, a bindrv reader context has to be allocated with a call to bindrv_newreader. This initialisation routine requires a callback function that is used for inputing data from some stream (e.g. use the C function fread to read from a file opened with the function fopen). The reader procedure has then to enter a loop calling first bindrv_nexttoken to get the type of the next token to read and then, depending on this data type, use the function suitable to read and decode this token. For instance if the function returns BINDRV_TYP_REAL, a real has to be read and the function bindrv_getreal can be used to get its value. If the file structure is known in advance, the data can be input with a sequence of calls to the decoding functions. For instance the data file of the example of the preceding section could be input with the following code:

int a,c;
char *l;

if(bindrv_getctrl(bctx,&c)==0 && (c==1))
{
 while(bindrv_getint(bctx,&a)==0)
  printf("got: %d\n",a);
 if(bindrv_getctrl(bctx,&c)!=0 || (c!=2))
  exit(1);
}
if(bindrv_getctrl(bctx,&c)==0 && (c==4))
{
 while(bindrv_getstring(bctx,&l)==0)
 {
  printf("got: %s\n",l);
  free(l);
 }
 if(bindrv_getctrl(bctx,&c)!=0 || (c!=2))
  exit(2);
}
if(bindrv_getctrl(bctx,&c)!=0 || (c!=3))
 exit(3);

As shown above, the application is in charge of releasing string buffers returned by bindrv_getstring: this routine allocates the returned memory block using the C function malloc. The application may replace this default memory allocator by calling function bindrv_setalloc.

Building files for Mosel

Data files generated for Mosel models must observe the same structure as the usual ascii Mosel format. For instance, consider the following data file in its ascii form:

a:123
b:[(1) 10]

The corresponding data stored in the binary format can be obtained with the following code:

bindrv_putctrl(bctx,BINDRV_CTRL_LABEL);
bindrv_putstring(bctx,"a");
bindrv_putint(bctx,123);
bindrv_putctrl(bctx,BINDRV_CTRL_LABEL);
bindrv_putstring(bctx,"b");
bindrv_putctrl(bctx,BINDRV_CTRL_OPENLST);
bindrv_putctrl(bctx,BINDRV_CTRL_OPENNDX);
bindrv_putint(bctx,1);
bindrv_putctrl(bctx,BINDRV_CTRL_CLOSENDX);
bindrv_putint(bctx,10);
bindrv_putctrl(bctx,BINDRV_CTRL_CLOSELST);

Note the use of control tokens to structure the data stream: a dedicated control code corresponds to each of the special characters in the ascii format. For example, the symbol '[' in the ascii format is represented by the code BINDRV_CTRL_OPENLST in the binary format.


© 2001-2024 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.