FSM API Documentation

Version 4.06

Irv.Elshoff@deltares.nl
12 nov 04

Contents


Introduction

FSM implements the MAKPTR, GETPTR, RELPTR and PTRKEY functions of FMM. And additional function - FSMINI  - is used to attach a process to a shared memory context, or create a local context. FSMINI must be called before the first invocation of MAKPTR, GETPTR, RELPTR or PTRKEY.

Function Specifications

FSMINI

integer function fsmini (contextid, flags)
    integer contextid
    integer flags

The FSM initialization routine attaches a Fortran process or thread to an existing shared memory context. These are created with the ESM create function or command.  It also set flags that control the operation of FSM.  The flags are specified by adding one or more of the following constants (at most once each):

If FSMINI is called with context ID zero, a local private context will be created.

The specified context ID becomes the current context. All other FSM functions operate within this context. A process can switch contexts by calling FSMINI again.  Subsequent calls operate in the new context, but in the previous context are still valid.  Use ESM (from C) to create and delete contexts.

Must be called exactly once for every thread (or process if threads are not being used) before calling all other FSM routines.

Returns one (FSM_OK) if successful or zero (FSM_ERROR) if an error occurred.

MAKPTR

integer function makptr (key, type, length)
    character key*(*)
    integer type
    integer length

The make pointer function allocates a new pointer, or returns the pointer associated with an existing key.  If the key already exists, it must have been made with the same type and length in a previous call, otherwise an error occurs. MAKPTR return the pointer of the new or existing key, or zero (FSM_ERROR) if an error occurred.

GETPTR

integer function getptr (key)
    character key*(*)

The get pointer function returns the pointer associated with the specified key, or zero (FSM_ERROR) if the key does not exist (or an error occurred).

RELPTR

integer function relptr (key)
    character key*(*)

The release pointer function frees the memory associated with the key, and removes the key from the key table.  It returns the newly invalid pointer upon success, or zero (FSM_ERROR) if the key does not exist or an error occurred.

PRTKEY

integer function prtkey

The print key routine writes to Fortran unit 5 (standard output) a human-readable listing of the current key table associated with the current context.  Useful for debugging.  See also ESM_ListContexts and ESM_ListRegions.  Always returns zero.

FSMERR

integer function fsmerr (string)
    character string*(*)

Write a description of the most recent FSM error message into the specified string.  Useful for when FSM_SILENT is on.  Always returns zero.

FSMTRF

integer function fsmtrf (filename)
    character filename*(*)

If the FSM_TRACE flag is set during initialization, a trace of every operation is written to standard output.  The FSMTRF function can be used to specify an alternative file.  Each thread that uses FSM can have its own trace file.  Returns FSM_OK upon success or FSM_ERROR if the file could not be created or appended to.