shcom_connect (3f)

allows a shared library's data to be shared between call_shared processes on DIGITAL UNIX systems

Syntax

  include 'shcom.f'

  integer*4 shcom_connect, status
  external shcom_connect
  integer*8 addr
  character*len file_name
  status = shcom_connect ( addr, file_name )

Parameters

  addr      Address of the structure to be shared. This acts as a "hook" into
            the shared library. Make sure the address of the structure
            element is passed by reference, not value.

  file_name Pathname of file to be used as "backing store" for sharing.
            Read/write permission is required. The file_name character array
            will be converted to a null terminated string.

  status    Contains the return code from the operation (see below).

Description

  The data to be shared among a set of processes should be organized as
  structures and built into a single shared library. Then, these processes
  should be linked against this shared library. Sharing of data starts when
  the processes perform the shcom_connect operation.  See shcom_connect(3)
  for implementation details, including application-level locking
  information.

  shcom_connect(3f) is explicitly for implementing "writeable shared COMMON"
  in DIGITAL Fortran and C. A BLOCK DATA subprogram is used to define the
  shared library of the COMMON blocks to be shared; COMMON blocks are used
  because they have global scope and their data can be both read and written.
  The user program calls the routine shcom_connect to explicitly load the
  shared library.

  shcom_connect maps the COMMONs declared in the user program onto the
  COMMONs of the same address (specified by using the first named variable in
  the matching COMMON block) in the shared library.  Reading and writing the
  data in the COMMONs affects the values in the shared library, which can be
  loaded simultaneously by multiple programs.

  The following restrictions must be observed for the correct sharing to take
  place:

  •    All data to be shared must reside in a COMMON block.

  •    Only COMMON blocks that will be shared should be listed in the BLOCK
       DATA subprogram used to build the .so.

  •    Each COMMON block listed in the BLOCK DATA must have at least one of
       its elements initialized via a DATA statement.

  •    The BLOCK DATA that defines the shared COMMONs must not declare any
       local data (that is, data that is not to be shared).

  Upon successful completion, the shcom_connect function returns zero.
  Otherwise, one of the following negative values is returned to indicate the
  error as defined by the INTEGER PARAMETERs in shcom.f:

    SHCOM_SUCCESS         =   0 /* success */

    SHCOM_LOADER_FAILED   =  -1 /* some loader call failed */

    SHCOM_BAD_ADDRESS     =  -2 /* user gave bad address */

    SHCOM_BAD_FILE        =  -3 /* cannot open or connect to filename */

    SHCOM_LOCK_FAILED     =  -4 /* locking operation failed */

    SHCOM_INIT_FAILED     =  -5 /* error initializing data in file */

    SHCOM_UNMAP_FAILED    =  -6 /* error unmapping shared library */

    SHCOM_MAP_FAILED      =  -7 /* error mapping shared file */

    SHCOM_MALLOC_FAILED   =  -8 /* can not malloc memory */

  The following example demonstrates the shcom_connect function:

    C
    C       FILE: shared_data.f - Example of initialized common data.
    C
            BLOCK DATA shared_block_data

            INTEGER*8 init_data
            REAL operand, result
            COMMON /shared_data/ init_data, operand, result

            DATA    init_data/42/, operand/0.0/, result/0.0/

            END

    C
    C       FILE: compute_agent.f - Example Fortran program
    C
            PROGRAM compute_agent
            INCLUDE '../include/shcom.f'

            INTEGER*8 init_data
            REAL operand, result
            COMMON /shared_data/ init_data, operand, result

            INTEGER shcom_connenct, stat
            EXTERNAL shcom_connenct

            stat = shcom_connect(init_data, '/tmp/shcom_demo')

            IF (stat .EQ. SHCOM_SUCCESS) THEN
                result = SQRT(operand)
            ELSE
                TYPE *, 'shcom_connect() failed, error = ', stat
            ENDIF

            STOP
            END

    /*
     * FILE ui_agent.c - Example of initialized common data written in C.
     */

    #include "shcom.h"

    typedef struct {
        long init_data;
        float operand;
        float result;
    } demo_t;

    extern demo_t shared_data_;

    main() {
        int stat;

        printf("shared_data_.init_data = %d\n", shared_data_.init_data);

        stat = shcom_connect(&shared_data_, "/tmp/shcom_demo");

        if (stat == SHCOM_SUCCESS) {
            shared_data_.operand = 2.0;
            shared_data_.result = 0.0;
            system("compute_agent");
            printf("shared_data_.result = %f\n", shared_data_.result);
        } else {
            printf("shcom_connect() failed, error = %d\n", stat);
        }
    }

    #
    #       FILE: Makefile  - Builds shared common example.
    #
    FC = f90
    CFLAGS = -g -I../include
    FFLAGS = -g
    LDFLAGS = -g
    LIBS = ../lib/libshcom.a

    all:    ui_agent compute_agent

    ui_agent:       ui_agent.o shared_data.so
            cc ${CFLAGS} -o ui_agent ui_agent.o shared_data.so ${LIBS}

    compute_agent:  compute_agent.o shared_data.so
            f90 ${FFLAGS} -o compute_agent compute_agent.o shared_data.so
  ${LIBS}

    shared_data.so: shared_data.o
            ld ${LDFLAGS} -shared -o shared_data.so shared_data.o -lc

    test:   shared_data.so ui_agent compute_agent
            LD_LIBRARY_PATH=.; export LD_LIBRARY_PATH; ui_agent

    clean:
            -rm -f ui_agent compute_agent
            -rm -f *.o shared_data.so
            -rm -f /tmp/shcom_demo so_locations

Files

  /usr/include/shcom.f          shcom_connect status values

  /usr/lib/libshcom.a           static library

  /usr/lib/libshcom.so          shared library

See Also

  ld(1), flock(2), mmap(2), munmap(2), open(2), loader(5)