Dynamic-Loading Functions

Introduction

As with any C program, program execution always begins with a function named main. The load module containing the main function must remain in memory at all times. Each subordinate (dynamically loaded) load module must contain a function named _dynamn (which is a contraction for dynamic main). From the perspective of the compiler, the _dynamn function serves the same role in the subordinate load module as main serves in the module containing the main program.

Cautions

• You cannot link a main function and a _dynamn function into the same load module. In particular, this means that you cannot have a source file which includes both these functions.
• You cannot create a C framework by calling a function that was compiled with the indep option into a load module which includes a _dynamn function.

Dynamic Load Modules

In addition to loadm and unloadm, the library provides functions to load and unload modules containing only data (loadd and unloadd ) and a function that converts a load module entry point address to a function pointer (buildm). Two other functions, addsrch and delsrch, are provided, primarily for CMS, to define the load module search order. The search order consists of the possible locations of dynamically loaded modules and the order in which they are processed. Before any of these routines can be used, the source program must include the header file <dynam.h> using the #include statement.

Transfers of control between load modules are possible only by using function pointers. However, through the use of appropriate pointers, a routine in one load module can call a routine in any other load module. The inability of one load module to call another directly is a special case of a more general restriction; namely, load modules cannot share external variables. More precisely, two external variables (or functions) of the same name in different load modules are independent of each other. (There are a few special cases such as the variable errno, which contains the number of the most recent run-time problem.) See Appendix 4, "Sharing extern Variables among Load Modules," in the SAS/C Compiler and Library User's Guide, Fourth Edition for additional information. An external variable or function can be accessed directly only by functions that have been linked in that module. All functions in other modules can gain access to them only by use of pointers.

The functions for dynamic loading, especially addsrch and delsrch, are highly operating-system-dependent. The definition of each dynamic-loading function highlights aspects of the function that depend in some way on the operating system. addsrch and delsrch , for example, are of interest to users working under MVS only when a program needs to be portable to CMS. For CMS, these functions are quite useful but are not needed typically in an MVS environment.

Function Descriptions

addsrch -- Indicate a "Location" from which Modules May Be Loaded

SYNOPSIS

 #include <dynam.h>

 SEARCH_P addsrch(int type, const char *loc,
                  const char *prefix);
 

DESCRIPTION

The first argument type must be a module type defined in <dynam.h>. The module type defines what type of module is loaded and varies from operating system to operating system. The character string specified by the second argument loc names the location. The format of this string depends on the module type. The third argument prefix is a character string of no more than eight characters.

addsrch is of interest primarily to CMS users and to MVS users writing programs portable to CMS. The remainder of this discussion, therefore, focuses on the use of addsrch under CMS.

CMS Argument Values

• CMS_NUCX specifies that the module is a nucleus extension. The module has been loaded (for example, by the CMS command NUCXLOAD) before loadm is called.
• CMS_LDLB specifies that the module is a member of a CMS LOADLIB file. The LOADLIB file must, of course, be on an accessed disk when loadm is called.
• CMS_DCSS specifies that the module resides in a named segment that has been created using the GENCSEG utility, as documented in Appendix 3, "The CMS GENCSEG Utility," in the SAS/C Compiler and Library User's Guide.

The module type also controls the format of the second argument loc, which names the location to be searched by loadm. If the module type is

• CMS_NUCX, the location parameter must be "".
• CMS_LDLB, the location parameter is the filename and filemode of the LOADLIB file in the form filename fm, for example, DYNAMC A1 specifies the file DYNAMC LOADLIB A1. The filemode may be *.
• CMS_DCSS, the location parameter is a one- to eight-character string that names the segment. An asterisk as the first character in the name is used to specify that the segment name is for a non-shared segment.

All location strings may have leading and trailing blanks. The characters are uppercased. addsrch does not verify the existence of the location.

The third argument is a character string of no more than eight characters. It may be "". If it is not null, then it specifies that the location indicated is searched only if the load module name (as specified by the first argument to loadm) begins with the same character or characters specified in the third argument.

At C program initialization, a default location, defined by the following call, is in effect:

 sp = addsrch(CMS_LDLB, "DYNAMC *","");
 

RETURN VALUE

CAUTION

USAGE NOTES

EXAMPLE

 #include <dynam.h>

 SEARCH_P mylib;
 .
 .
 .
    /* Search for modules in a CMS LOADLIB. */
 mylib = addsrch(CMS_LDLB, "PRIVATE *", "");
 

buildm -- Create a Function Pointer from an Address

SYNOPSIS

 #include <dynam.h>

 void buildm(const char *name, __remote /* type */  (**fpp)(),
             const char *ep);
 

DESCRIPTION

buildm stores the function pointer in the area addressed by fpp. Note that fpp may reference a function returning any valid type of data. If the function pointer cannot be created, a NULL value is stored.

name points to a name to be assigned to the built load module. If name is "", then a unique name is assigned by buildm. If the name is prefixed with an asterisk, then buildm does not check to see if the name is the name of a previously loaded module (see "ERRORS", below).

RETURN VALUE

ERRORS

CAUTIONS

The fpp argument must be a pointer to an object declared as "pointer to function returning (some C data type)".

EXAMPLE

The example assumes that SIMPLE is a C _dynamn function returning void.

 #include <svc.h>
 #include <code.h>
 #include <stdio.h>

 #define LOAD(n,ep) (_ldregs(R0+R1,n,0),_ossvc(8),
         _stregs(R0,ep))

 main()
 {

    void (*fp)();
    char *ep;

       /* The name "SIMPLE" must be uppercased, left-adjusted, */
       /* and padded to eight characters with blanks when      */
       /* used by SVC 8.                                       */
    LOAD("SIMPLE  ",&ep);

       /* The name passed to buildm does not have to match     */
       /* the name of the loaded module, but it helps.         */
    buildm("simple",&fp,ep);
    if (fp)         /* If no errors, call SIMPLE               */
       (*fp)();
    else
       puts("simple didn't load.");

 }
 

delsrch -- Delete a "Location" in the Load Module Search Order List

SYNOPSIS

 #include <dynam.h>
 void delsrch(SEARCH_P sp);
 

DESCRIPTION

PORTABILITY

EXAMPLE

 #include <dynam.h>

 SEARCH_P source;
 char *new_source;
 .
 .
 .
    /* Delete old search location.  */
 if (source) delsrch(source);
    /* Add new search location.     */
 source = addsrch(CMS_LDLB, new_source, "");
 

loadd -- Dynamically Load a Load Module Containing Data

SYNOPSIS

 #include <dynam.h>

 void loadd(const char *name, char **dp, MODULE *mp);
 

DESCRIPTION

If the module has been loaded already, the pointer returned in the second argument points to the previously loaded copy. If the module name in the first argument string is prefixed with an asterisk, a private copy of the module is loaded.

The third argument addresses a location where a value is stored that can be used later to remove the module from memory via unloadd. loadd should be used only to load modules that contain data (for example, translation tables) rather than executable code.

RETURN VALUE

ERRORS

CAUTION

PORTABILITY

IMPLEMENTATION

Under CICS, modules to be loaded must reside in a library in the DFHRPL concatenation, and must be defined to CICS.

EXAMPLE

 #include <dynam.h>
 #include <lcstring.h>

 char *table;
 char *str;
 MODULE tabmod;
    /* Load a translate table named LC3270AE.                     */
 loadd("LC3270AE",&table,&tabmod);
 str = strxlt(str, table);
 unloadd(tabmod);                      /* Unload module after use.*/
 

loadm -- Dynamically Load a Load Module

SYNOPSIS

 #include <dynam.h>;

 void loadm(const char *name, __remote /* type */  (**fpp)());
 

DESCRIPTION

RETURN VALUE

If the module to be loaded cannot be found, a NULL is stored in the location addressed by fpp.

ERRORS

CAUTIONS

The second argument must be a pointer to an object declared as "pointer to function returning (some C data type)."

Note that a module to be loaded by loadm cannot have the entry point defined in the last 16 bytes of the load module. The library inspects this portion of the loaded module, and may ABEND if 16 bytes of data are not present. This situation can arise only if the entry point is an assembler (or other non-C) routine.

PORTABILITY

IMPLEMENTATION

Under CICS, modules to be loaded must reside in a library in the DFHRPL concatenation and must be defined to CICS.

USAGE NOTES

If loadm determines that a location is inaccessible (for example, the LOADLIB does not exist), the location is marked unusable, and no attempt is made to search it again.

EXAMPLES

The second example creates a dynamic load module that includes a table of pointers to functions which may be called dynamically from the calling load module. This example runs under MVS and has been designed to provide a framework that can be expanded upon in complete application.

The third example presents a hypothetical situation under CMS in which

1. the load module is created
2. the load module's location is added to the list of locations from which modules can be loaded (addsrch )
3. the load module is loaded (loadm )
4. the load module is deleted from the search order list (delsrch ).

Example 1.1 simple case

 #include <dynam.h>

 int (*fp)();
    /* Load a load module named "ADD" and call it. */
 loadm("ADD",&fp);
 sum = (*fp)(1, 3);
 .
 .
 .
 

Example 1.2 dynamic loading modules with multiple functions

STEP I. Put the following declarations in a common header file and name it DYNTABLE:

 struct funcdef {           /* structure definition for functions     */
    int (*func1)();
    int (*func2)();
                             /* More functions can go here.           */
 };

 typedef struct funcdef *fptrtable;  /* pointer to list of funcdefs   */
 

STEP II. Create the following C source file and name it DYNAMIC. This file will be compiled and linked to create a dynamic load module. The _dynamn function returns to its caller a structure of function pointers that can be used to call the individual functions of the load module.

 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>
 #include <lcio.h>
 #include <dynam.h>
 #include "dyntable.h"

    /* _dynamn function that returns a list of function pointers which */
    /* can be used to invoke other functions in the load module        */
 fptrtable _dynamn(void) {
       /* Initialize function pointer table.                           */
    static struct funcdef dyntab = {&func1, &func2 /* ... */ };
       /* Return pointer to table with the new contents.               */
    return(&dyntab);
 }

 int func1() {
   printf("func1() was successfully dynamically called!!!\n");
   return(0);
 }

 int func2() {
   printf("func2() was successfully dynamically called!!!\n");
   return(0);
 }
 

STEP III. Create the following C source file and name it DYNMLOAD. This code demonstrates how to dynamically load the DYNAMIC load module and how to call the functions pointed to by the dyntab table:

 #include <stdio.h>
 #include <string.h>
 #include <dynam.h>
 #include "dyntable.h"

 fptrtable(*fpdyn)();  /* _dynamn function pointer prototype       */

 int rc1, rc2;         /* return codes from calling func_1         */
                       /* and func_2                               */

 fptrtable table;      /* table of function pointer and names      */
                       /* returned from _dynamn                    */
 main()
 {
       /* Load DYNAMIC.                                            */
    loadm("DYNAMIC", &fpdyn);

       /* Call _dynamn and return table of function pointers and   */
       /* name of load module.                                     */
    table = (*fpdyn)();

       /* Call func1 using function pointer from table.            */
    rc1 = (*table->func1)();
    printf("Dynamically called func1() with rc = %d \n", rc1);

       /* Call func2 using function pointer from table.            */
    rc2 = (*table->func2)();
    printf("Dynamically called func2() with rc = %d \n", rc2);

    unloadm(fpdyn);
    return;
 }
 

 //*
 //*   COMPILE and LINK module that uses a _dynamn routine that passes
 //*   its caller back a list of function pointers which are used to
 //*   invoke other functions in the load module
 //*
 //COMPDYNM EXEC LC370CL,ENTRY=DYN,PARM.C='RENT SNAME(DYNAM)'
 //C.SYSLIN   DD DSN= userid .SASC.OBJ(DYNAMIC),DISP=OLD
 //C.SYSIN    DD DSN= userid .SASC.SOURCE(DYNAMIC),DISP=SHR
 //*
 //LKED.SYSLMOD  DD DSN= userid .SASC.LOAD(DYNAMIC),DISP=OLD
 //*
 //*
 //*   COMPILE and LINK module that dynamically loads the DYNAMIC
 //*   load module and calls functions within the load module
 //*   using the structure of function pointers returned.
 //*
 //CLEMAIN EXEC LC370CLG
 //C.SYSLIN   DD DSN= userid .SASC.OBJ(DYNMLOAD),DISP=OLD
 //C.SYSIN    DD DSN= userid .SASC.SOURCE(DYNMLOAD),DISP=SHR
 //*
 //LKED.SYSLMOD  DD DSN= userid .SASC.LOAD(DYNMLOAD),DISP=OLD
 //
 

Example 1.3 dynamic loading under CMS

 #include <stdio.h>

 void neptune(char *p) {
    puts(p);
    return;
 }
 

1. Rename the function to _dynamn.

    #include <stdio.h>
   
    void _dynamn(char *p) {
       puts(p);
       return;
    }
    

   All C load modules (except the one that includes main, of course) must define one function named _dynamn.
2. Recompile NEPTUNE C, using the sname compiler option to override the default assignment of _dynamn as the sname. See Chapter 7, "Compiler Options," in the SAS/C Compiler and Library User's Guide, Fourth Edition for more information about the sname compiler option.
3. Link-edit the resulting NEPTUNE TEXT file using the CMS command LKED. The LIBE and NAME options of the LKED command can be used to specify the name of the output LOADLIB file and member name, respectively. For example,

    LKED NEPTUNE (LIBE DYNAMC NAME NEPTUNE
    

STEP II. The function neptune now exists in a form loadable by loadm. Invoke loadm to load the module as follows:

 #include <dynam.h>
 main()
 {
    int (*fp)();               /* Declare a function pointer */
    loadm("NEPTUNE",&fp);      /* Load NEPTUNE           */
       if (fp) {               /* Check for errors           */
          (*fp)("Hello, Neptune, king of the C!");
          unloadm(fp);         /* Delete NEPTUNE             */
       }
       else
          puts("NEPTUNE failed to load.");
     exit(0);
 }
 

 #include <dynam.h>

 main()
 {
    SEARCH_P sp;                    /* Declare a SEARCH_P value  */
    int (*fp)();
       /* specify "NEWLIB LOADLIB *" */
    sp = addsrch(CMS_LDLB,"NEWLIB *","");
    loadm("NEPTUNE",&fp);
    if (fp) {
       (*fp)("Hello, Neptune, king of the C!");
       unloadm(fp);
    }
    else
       puts("NEPTUNE failed to load.");
    delsrch(sp);  /* remove NEWLIB LOADLIB from the search order */
    exit(0);
 }
 

 sp = addsrch(CMS_NUCX,"","");
 loadm("NEPTUNE",&fp);
 

unloadd -- Discard a Previously Loaded Data Module

SYNOPSIS

 #include <dynam.h>;

 void unloadd(MODULE mp);
 

DESCRIPTION

RETURN VALUE

ERRORS

CAUTION

EXAMPLE

unloadm -- Discard a Previously Loaded Module

SYNOPSIS

 #include <dynam.h>

 void unloadm(__remote /* type */  (*fp)());
 

DESCRIPTION

unloadm may be used to unload a module that has been built by buildm, but unloadm will not delete the module from memory.

RETURN VALUE

ERRORS

CAUTION

EXAMPLE

 #include <dynam.h>

 int (*fp)();
    /* Load a load module named "IEFBR14", */
    /* call it, and unload it.             */
 loadm("iefbr14",&fp);
 (*fp)();
 unloadm(fp);
 

Copyright (c) 1998 SAS Institute Inc. Cary, NC, USA. All rights reserved.