Writing the cstubs.c Module

The cstubs.c module is the source code module that contains the external subroutines that are called with a LINK statement from logic. The source code module must be compiled or assembled before linking in PROIV. The arguments to the subroutines are passed by reference in the order and number specified by the corresponding LINK statement. All parameters are passed to external subroutines, as ‘C’ strings for example, are Null terminated. The following is an example of a cstubs.c module written in 'C'.

Example

This is an example of cstubs written in 'C'

/*********************************************************************
*                                                                    *
* cstubs.c - external subroutines                                    *
*                                                                   *
**********************************************************************
* External Subroutines 0 - 9                                         *
* Each argument is passed by reference in the order and number       *
* specified by the corresponding LINK statement in PROIV logic       *
*********************************************************************/
sub0(num1,num2)
char *num1, *num2;
/*********************************************************************
* Local Data storage area                                            *
*********************************************************************/
{
          bytmov (num1,num2,7);
}

sub1(name1,name2)
/*********************************************************************
* Local data storage area                                            *
*********************************************************************/
char *name1,*name2;
{
            puts ("\nSubroutine 1");
            printf("First argument is %8.4s\n", name1);
            printf("Second argument is %8.5s\n",name2;
            puts ("\nPress <RET> to continue");
            getchar ( );
}

sub2(name1,name2)
/*********************************************************************
* Local data storage area                                           *
*********************************************************************/
char *name1,*name2;

{
            puts ("nSubroutine 2");
            strncpy (name1,"derf",4);
            printf("First argument is %8.4s\n", name1);
            strncpy (name2, "cakes",5);
            printf("Second argument is %8.5s\n", name2);
            puts ("\nPress <RET> to continue");
            getchar ( );
}

sub3(name1,name2)
/*********************************************************************
* Local data storage area                                            *
*********************************************************************/
char *name1,*name2;
{
            puts ("\nSubroutine 3");
            name1[5] - '\0';
            name2[6] - '\0';
            printf("First argument is %s\n", name1);
            printf("Second argument is %s\n", name2);
            puts ("\nPress <RET> to continue");
            getchar ( );
}

/*********************************************************************
* Unused entries should be defined to avoid Link warning messages *
* but will not actually be invoked *
*********************************************************************/
sub4( )
{
}
sub5( )
{
}
sub6( )
{
}
sub7( )
{
}
sub8( )
{
}
sub9( )
{
}

Each string parameter is null terminated.
As an aid for developers, the maximum allocated length of a string parameter is also passed in a single byte that can be accessed at string parameter position -1. For example, in 'C', if a parameter is passed as follows:

sub0(param)
char *param

The length can be accessed using:

len = *(param-1);

You must not write more characters into a referenced string variable than exist when your function was called. This will overwrite other variables when returned to PROIV and may result in that string being truncated.
All PROIV interrupt handlers are still in place during execution of external routines.
Any variables declared outside of functions should be declared 'static' to avoid name clashes with PROIV globals. Similarly, any local functions should be declared as 'static'.

Comment on this topic

Topic ID: 720279