basic.cfunc.user Definition/BASIC Program

basic.cfunc.user

Command basic.cfunc.user Definition/BASIC Program
Applicable release versions: AP/Unix
Category BASIC Program (486)
Description can be incorporated in the Pick Monitor, thus making C functions available to all applications running on the system.
This way of 'customizing' the Monitor should be reserved to functions which are widely used in the applications running on the system (such as a math package, graphics, communications, etc.). It is a fairly complex procedure which should be attempted only by programmers experienced both in Pick and Unix or DOS.

The main advantage of this procedure is efficiency. The cost, however, is obviously the loss of portability to non Advanced Pick/Unix platforms. Also, the user-defined built-in function must be integrated in the Monitor at every new release.

Integrating a C function in the Monitor requires the following steps:

- Build a table to inform the Pick/BASIC compiler about the new user written function.

- Build a branch table which will be used by the Monitor to access the user written function.

- Create a new Monitor.

The following describes the necessary procedures through the example shown in the 'example' section below. The tools used in this section are described completely under their respective entries in the documentation.

It must be emphasized that, especially while debugging with Unix debuggers, changing data in the Pick environment can cause damage to the data base.

Most of the following procedures can be done from TCL (by prefixing Unix commands with a "!"). The Pick process has to be stopped (disconnected), however, when the new Monitor is about to be created, since most Unix versions will not allow rebuilding an object module which is currently being executed.

The steps required for adding a new function to the Monitor are:

- Step 1: Logon to the dm account.

- Step 2: Add the new module to the Pick/BASIC-C interface.

addbi fpadd fpsub fpmul fpdiv

The "addbi" commands adds the functions to the item dm,messages, user.builtin and creates and compiles the file px_user.c which is the built-in User branch table.

This step needs to be done only once.

- Step 3: Edit and compile the C program

After entering the C program, compile it:

!cc -c fp.c

This creates the module fp.o.

- Step 4: Add the new module to the user function library
!ar vru libgmu.a fp.o

- Step 5: Disconnect the current Pick Process

If the current line is the line 0, the Pick virtual machine will shutdown. At this stage, since user processes normally execute the reference Monitor /usr/bin/ap, it is not necessary to stop the virtual machine.

disc

This drops back to the shell.

- Step 6: Build the new monitor.

make -f /usr/lib/pick/Makefile

This creates a monitor named ap on the current directory. If errors occur while "make"ing it may be necessary to make modifications to the Makefile (see Makefile).

- Step 7: Test the new Monitor

Generally, it is not necessary to shutdown the Pick virtual machine to start a user process on a new Monitor. The new Monitor can be executed by one or more user processes for test purpose. Just type:

./ap

This will start a User process executing the new Monitor. To make any change, repeat the procedure from steps 3 to 7 until the C function is working properly. Debugging can be done with the usual Unix debuggers like sdb or dbx.

Logon to dm. Enter the following Pick/BASIC program:

bp fpdiv:

cfunction unix.builtin, user.builtin
*
* Reserve space for the resulting string
char result[64]
*
* Call the C function (no return code)
%fpdiv( "1.23e-9", "1.2e-3", result, 64)
*
* Extract result (0 terminated string)
print 'Res=':field(result,char(0),1)

Compile it and run it:

compile bp fpdiv
run bp fpdiv

Res=1.02500000000000013890527183341e-06

Repeat steps 3 to 7 until the new function works properly.

- Step 8: Move the monitor to the working directory.

When the new Monitor is properly tested, it can be moved to the common directory, where Users can access it. Copying the new Monitor must be done as super-user (root) since the directory is write protected.

su (enter password)
chmod 06755 ap
chown root ap
cp ap /usr/bin
Shutdown and reboot the Pick virtual machine. User processes now execute the new monitor.
Syntax
Options
Example
Consider the following C functions which perform the four basic operations on 
two strings, s1 and s2, representing floating point numbers in FORTRAN F-format 
or E-format ("[-]d.dddE[+-]dd"). A string, up to p characters long, 
representing the result, is returned into s3.

fp.c : 

double atof(); 
fpadd( s1, s2, s3, p)
char *s1, *s2, *s3;
int p;
{
  gcvt( atof(s1)+atof(s2), p, s3 );
} 

fpsub( s1, s2, s3, p)
char *s1, *s2, *s3;
int p;
{
  gcvt( atof(s1)-atof(s2), p, s3 );
} 

fpmul( s1, s2, s3, p)
char *s1, *s2, *s3;
int p;
{
  gcvt( atof(s1)*atof(s2), p, s3 );
} 

s1, s2, s3, p)
char *s1, *s2, *s3;
int p;
{
  gcvt( atof(s1)/atof(s2), p, s3 );
}
Purpose
Related basic.cfunction
tcl.listbi
tcl.addbi.apdos
basic.cfunc
basic.%
flash.basic.differences
tcl.addbi.unix