Data structures and other definitions for the ESF Manager Processing Environment.
Definition in file saf-env.h.
This graph shows which files directly or indirectly include this file:
Go to the source code of this file.
Defines | |
| #define | SafENV_H |
| #define | SafESM_LCK_CHG 0 |
| change from shared to exclusive lock | |
| #define | SafESM_LCK_HAVE 1 |
| ignore if already hold lock | |
| #define | SafESM_LCK_TEST 2 |
| test but do not lock | |
| #define | SafESM_LCK_USE 3 |
| do not wait if already locked | |
| #define | SafESM_LCK_NOWAIT 3 |
| do not wait if already locked | |
| #define | SafESM_LCK_NONE 4 |
| normal processing | |
| #define | SafESM_LCK_UOW 11 |
| lock ends when unit of work ends | |
| #define | SafESM_LCK_TASK 12 |
| lock ends when task ends | |
| #define | SafESM_LCK_PROC 13 |
| lock ends when process ends | |
| #define | SafESM_LCK_SHR 0 |
| shared (read) lock | |
| #define | SafESM_LCK_EXCL 1 |
| exclusive (write) lock | |
Enumerations | |
| enum | SafMsgLvl { SafMsgINFO, SafMsgWARN, SafMsgERR, SafMsgCRIT, SafMsgInvalid } |
| Log Message Level. More... | |
| enum | SafLockRet { SafLockOK = 0, SafLockOWN = 1, SafLockHELD = 2, SafLockNHELD = 3, SafLockNEXIST = 4, SafLockDENY = 5, SafLockERR = 6, SafLockPARAM = 7, SafLockInvalid } |
| Lock Return Codes. More... | |
Functions | |
| mf_uns32 | SafEnvInit (struct SafInit *) |
| ESF Environment Initialization. | |
| SafRet | SafShmOpen (const char *Name, size_t *Size, void **Area) |
| Open named "shared" memory. | |
| SafRet | SafModLoad (const char *ModPath, struct SafPTab *(**Entry)(void)) |
| Load a module. | |
| SafRet | SafModUnload (const char *ModPath) |
| Unload a module. | |
| SafRet | SafGetInstPath (char *Path, size_t MaxLen) |
| Get product installation base path. | |
| SafRet | SafLog (int Num, enum SafMsgLvl, const char *DefaultText,...) |
| Log a message. | |
| SafRet | SafLogLit (int Num, enum SafMsgLvl Level, const char *Text) |
| Log a literal message. | |
| SafRet | SafAceeAlloc (const char *Name, const char *Group, struct SafACEE **AceeP, int *IsNew) |
| Allocate an ACEE. | |
| SafRet | SafAceeIterate (void *Data, int(*Callback)(struct SafACEE *Acee, void *Data)) |
| Iterate over ACEEs. | |
| SafLockRet | SafLockEnq (const char *QName, const char *RName, int Type, int Exclusive, int Lifetime) |
| Acquire a named lock (enqueue). | |
| SafLockRet | SafThrLock (const char *Name, int Exclusive) |
| Acquire a named lock, if the environment is multithreaded. | |
| SafLockRet | SafShmLock (const char *Name, int Exclusive) |
| Acquire a named lock, if the environment uses shared memory. | |
| SafLockRet | SafLockDeq (const char *QName, const char *RName) |
| Release a named lock (dequeue). | |
| SafLockRet | SafThrUnlock (const char *Name) |
| Release a named lock, if the environment is multithreaded. | |
| SafLockRet | SafShmUnlock (const char *Name) |
| Release a named lock, if the environment uses shared memory. | |
| int | SafIsMT (void) |
| Identify multithreaded environments. | |
| int | SafIsSharedMemory (void) |
| Identify multiprocess shared-memory environments. | |
| int | SafStrcmpCI (const char *, const char *) |
| Case-insensitive string comparison. | |
| int | SafStrcmpCIN (const char *, const char *, size_t) |
| Case-insensitive string comparison (length-limited). | |
| char * | SafDupStr (const char *) |
| Duplicate a string. | |
| SafRet | SafAllocStore (struct SafStore **StoreP) |
| Create a store. | |
| SafRet | SafFreeStore (struct SafStore *Store) |
| Free a store and the class and name data in it. | |
| SafRet | SafClearStore (struct SafStore *Store) |
| Remove all the data from a store. | |
| SafRet | SafStoreRemove (struct SafStore *Store, const char *C, const char *N) |
| Remove an entry from a store. | |
| SafRet | SafStoreIterate (struct SafStore *Store, const char *Class, SafRet(*Visitor)(const char *Class, const char *Name, void *Value, void *Data), void *Data, SafRet *VisitorErrP) |
| Iterate over a store, optionally filtering for a single class. | |
| SafRet | SafStoreAdd (struct SafStore *S, const char *C, const char *N, void *P) |
| Add an entry to a store. | |
| SafRet | SafStoreFind (struct SafStore *S, const char *C, const char *N, void **P) |
| Retrieve an entry from a store. | |
| SafRet | SafStoreLoad (struct SafStore *Store, const char *Text) |
| Load a store from structured text. | |
| int | SafVSnprintf (char *Buffer, size_t BufLen, const char *Format, va_list Args) |
| int | SafSnprintf (char *Buffer, size_t BufLen, const char *Format,...) |
| SafRet | SafGetEnvFunc (int(**FuncP)(), const char *Name, const char *Env) |
| enum SafMsgLvl |
| enum SafLockRet |
Lock Return Codes.
These are the return codes from the lock-management functions, SafLockEnq() and SafLockDeq().
| mf_uns32 SafEnvInit | ( | struct SafInit * | Init | ) |
ESF Environment Initialization.
For internal use only.
This function is invoked by the ESF Manager Initialization routine to set the processing environment.
| [in] | Init | ESF Manager initialization area (see SafInit). |
Definition at line 299 of file saf-env.c.
References SafInit::Environment, SafENV_CAS, SafENV_MFDS, SafENV_MTOMASK, SafENV_SOLO, SafINIT_ENV, SafINIT_INTERNAL, and SafINIT_OK.
| SafRet SafShmOpen | ( | const char * | Name, | |
| size_t * | Size, | |||
| void ** | Area | |||
| ) |
Open named "shared" memory.
Attach to an existing named memory area, or create it if it does not already exist. The area will be available to all ESF Manager and ESM Module instances in the current environment. In CAS, that means it's actually in the CAS shared memory segment; in MFDS, it's normal process-private memory.
| [in] | Name | Name of the area being opened. |
| [in,out] | Size | Size of the area to create, if it does not already exist; actual size on return, if it does already exist. |
| [out] | Area | Returns a pointer to the area. |
Definition at line 791 of file saf-env.c.
References SafR_PARAM, and SafR_STATE.
Referenced by EsmGetSharedMem().
Load a module.
Load the named module into the process. The module should be an OS loadable object (DLL on Windows, CSO on Unix); on Windows, it is also possible to use a loadable COBOL module (int code or gnt code), but this is discouraged (because of poor error reporting by cobgetfuncaddr and other issues).
All modules loaded by ESF Manager follow the same conventions: they export an initial entry point which takes no parameters and returns a pointer to an array of function pointers. See the ESM Module Interface.
| [in] | ModPath | Pathname of module to load. Searching the load path is also supported, but unwise (since this is security-sensitive). Note that the ESM Interface always passes an absolute path. |
| [out] | Entry | Pointer to function pointer which will be set to the initial entry point exported by the module. |
Definition at line 398 of file saf-env.c.
References Entry, Path, SafDupStr(), SafR_EXFAIL, SafR_INTERNAL, SafR_INVALID, SafR_NOTFOUND, SafR_OK, SafR_PARAM, SafR_RESOURCE, SafSTRCMP, SafThrLock(), and SafThrUnlock().
| SafRet SafModUnload | ( | const char * | ModPath | ) |
Unload a module.
Unload the named module, if it was previously loaded by SafModLoad. The ModPath parameter must match the path passed to SafModLoad.
| [in] | ModPath | Pathname of module to unload. |
Definition at line 606 of file saf-env.c.
References Handle, Path, SafR_EXFAIL, SafR_NOTFOUND, SafR_OK, SafR_PARAM, SafSTRCMP, SafThrLock(), and SafThrUnlock().
Referenced by SafEsmUnload().
| SafRet SafGetInstPath | ( | char * | Path, | |
| size_t | MaxLen | |||
| ) |
Get product installation base path.
Determine the base path for the current product.
| [out] | Path | Buffer for returned path, as a null-terminated string. |
| [in] | MaxLen | Maximum length of the returned path, including the terminating null. |
Definition at line 814 of file saf-env.c.
References SafR_EXFAIL, SafR_NOTFOUND, SafR_OK, SafR_RESOURCE, and SafR_TRUNCATED.
Log a message.
Log a message with an environment-specific logging facility. We attempt to get message text for the current language (using the COBOL RTS NLS routines); if that fails, we use the default text supplied by the caller. (This is also convenient for developers and maintainers, who can see what message is being logged without looking up the message number.) Messages are treated as snprintf format strings, but they're scanned and only message text with whitelisted substitutions are allowed through.
NLS implementation notes: CBL_NLS_GET_MSG is used to retrieve message text on all platforms. CBL_NLS_GET_MSG will do formatting, but we don't let it; all the messages in the catalog should have percent-signs doubled to prevent CBL_NLS_GET_MSG from trying to process them. See safmgr.err for examples; that's also where new messages should be added. safmgr.err is compiled into safmgr.lng, which should go in the same directory as the ESF Manager shared object.
| [in] | Num | Message number (see ESF Manager Messages and Logging) |
| [in] | Level | Message level (see SafMsgLvl) |
| [in] | DefaultText | Default message text |
| [in] | ... | Substitution parameters |
Definition at line 1001 of file saf-env.c.
References SafR_EXFAIL, SafR_INTERNAL, SafR_OK, SafR_PARAM, SafR_STATE, snprintf, and vsnprintf.
Referenced by SafAdmin(), SafAuth(), SafEsmExit(), SafGetEnvFunc(), SafRaiseAuditEvent(), SafUpdate(), SafVerify(), and SafXauth().
Log a literal message.
This is similar to SafLog(), except that it does no formatting other than prefixing the message with the prefix, number, and level indicator. (Some of that may be environmentally specific, which is why it happens here.) Also, no NLS lookup is performed.
| [in] | Num | Message number, as for SafLog(). |
| [in] | Level | Message level, as for SafLog(). |
| [in] | Text | Formatted message text. |
Definition at line 1196 of file saf-env.c.
References SafR_EXFAIL, SafR_PARAM, SafR_STATE, and snprintf.
Referenced by EsmLog().
Allocate an ACEE.
Allocate or find an ACEE structure. Every verified user has an ACEE; this function will locate the ACEE if it exists, or create one if it does not. In the CAS environment, ACEEs are shared and managed by the environment; in other environments, we fake them.
The full key for the ACEE is actually Name and Group, since users can sign in under different groups. (This has no effect under some ESMs, but others honor it.)
| [in] | Name | The unique name for the ACEE, which should be the user's short name (max 8 characters). |
| [in] | Group | Optional group name (max 8 characters). |
| [out] | AceeP | The returned ACEE pointer. |
| [out] | IsNew | Optional flag for whether this ACEE was created new (or an existing one was retrieved). |
Definition at line 1248 of file saf-env.c.
References SafR_PARAM, and SafR_STATE.
Referenced by EsmGetAcee(), and SafVerify().
Iterate over ACEEs.
Iterate over all existing ACEE structures. Every verified user has an ACEE; in all-groups mode, each verified {user, signon-group} pair will have a distinct ACEE. This function calls a callback supplied by the caller for each ACEE.
Iteration ends with the last ACEE, or when the callback returns a non-zero value.
| [in] | Data | Pointer to any data the caller wishes to pass to the callback. (This could be an allocated area which the callback uses to pass data back to the caller, of course.) |
| [in] | Callback | A pointer to a function/procedure that takes a pointer to an ACEE and a pointer to arbitrary data (which will be the Data parameter described above), and returning an int. |
Definition at line 1286 of file saf-env.c.
References SafR_PARAM, and SafR_STATE.
Referenced by EsmAceeIterate().
| SafLockRet SafLockEnq | ( | const char * | QName, | |
| const char * | RName, | |||
| int | Type, | |||
| int | Exclusive, | |||
| int | Lifetime | |||
| ) |
Acquire a named lock (enqueue).
Enqueue on a named lock object. See EsmLockEnq() for more information.
| [in] | QName | Queue (class) name of lock object, a nul-terminated string (max 8 characters, no spaces) |
| [in] | RName | Resource name of lock object, a nul-terminated string (max 255 characters) |
| [in] | Type | Operation type; see Lock Operation Types |
| [in] | Exclusive | Whether lock is shared (zero) or exclusive (non-zero); see Lock Exclusivity |
| [in] | Lifetime | Lock lifetime; see Lock Lifetimes |
Definition at line 1314 of file saf-env.c.
References SafESM_LCK_NONE, SafESM_LCK_PROC, SafLockERR, and SafLockPARAM.
Referenced by EsmLockEnq(), SafShmLock(), and SafThrLock().
| SafLockRet SafThrLock | ( | const char * | Name, | |
| int | Exclusive | |||
| ) |
Acquire a named lock, if the environment is multithreaded.
If MultiThreaded is set, call the real locking function; otherwise a no-op. See EsmLockEnq() for more information. QName is always "#ESFMgr"; Type is always SafESM_LCK_NONE; Lifetime is always SafESM_LCK_PROC.
| [in] | Name | Resource name of lock object, a nul-terminated string (max 255 characters) |
| [in] | Exclusive | Whether lock is shared (zero) or exclusive (non-zero); see Lock Exclusivity |
Definition at line 1348 of file saf-env.c.
References SafESM_LCK_NONE, SafESM_LCK_PROC, and SafLockEnq().
Referenced by SafModLoad(), SafModUnload(), and safterm().
| SafLockRet SafShmLock | ( | const char * | Name, | |
| int | Exclusive | |||
| ) |
Acquire a named lock, if the environment uses shared memory.
If SharedMemory is set, call the real locking function; otherwise a no-op. See EsmLockEnq() for more information. QName is always "#ESFMgr"; Type is always SafESM_LCK_NONE; Lifetime is always SafESM_LCK_PROC.
| [in] | Name | Resource name of lock object, a nul-terminated string (max 255 characters) |
| [in] | Exclusive | Whether lock is shared (zero) or exclusive (non-zero); see Lock Exclusivity |
Definition at line 1378 of file saf-env.c.
References SafESM_LCK_NONE, SafESM_LCK_PROC, and SafLockEnq().
| SafLockRet SafLockDeq | ( | const char * | QName, | |
| const char * | RName | |||
| ) |
Release a named lock (dequeue).
Dequeue on a named lock object. See EsmLockDeq() for more information.
| [in] | QName | Queue (class) name of lock object, a nul-terminated string (max 8 characters, no spaces) |
| [in] | RName | Resource name of lock object, a nul-terminated string (max 255 characters) |
Definition at line 1407 of file saf-env.c.
References SafLockERR, and SafLockPARAM.
Referenced by EsmLockDeq(), SafShmUnlock(), and SafThrUnlock().
| SafLockRet SafThrUnlock | ( | const char * | Name | ) |
Release a named lock, if the environment is multithreaded.
If MultiThreaded is set, call the real locking function; otherwise a no-op. See EsmLockDeq() for more information. QName is always "#ESFMgr".
| [in] | Name | Resource name of lock object, a nul-terminated string (max 255 characters) |
Definition at line 1431 of file saf-env.c.
References SafLockDeq().
Referenced by SafModLoad(), SafModUnload(), and safterm().
| SafLockRet SafShmUnlock | ( | const char * | Name | ) |
Release a named lock, if the environment uses shared memory.
If SharedMemory is set, call the real locking function; otherwise a no-op. See EsmLockDeq() for more information. QName is always "#ESFMgr".
| [in] | Name | Resource name of lock object, a nul-terminated string (max 255 characters) |
Definition at line 1451 of file saf-env.c.
References SafLockDeq().
| int SafIsMT | ( | void | ) |
Identify multithreaded environments.
Return the value of the MultiThreaded internal variable, which is non-zero if the environment is multithreaded.
Definition at line 1468 of file saf-env.c.
Referenced by EsmSafQuery(), and SafAllocStore().
| int SafIsSharedMemory | ( | void | ) |
Identify multiprocess shared-memory environments.
Return the value of the SharedMemory internal variable, which is non-zero if the environment has multiple processes commmunicating with shared memory.
| int SafStrcmpCI | ( | const char * | Str1, | |
| const char * | Str2 | |||
| ) |
Case-insensitive string comparison.
Like strcmp, but case-insensitive (in the current locale). Can be used with the SafSTRCMP_CI macro.
| [in] | Str1 | First string to be compared. |
| [in] | Str2 | Second string to be compared. |
| int SafStrcmpCIN | ( | const char * | Str1, | |
| const char * | Str2, | |||
| size_t | Len | |||
| ) |
Case-insensitive string comparison (length-limited).
Like strncmp, but case-insensitive (in the current locale). Can be used with the SafSTRCMP_CIN macro.
| [in] | Str1 | First string to be compared. |
| [in] | Str2 | Second string to be compared. |
| [in] | Len | Maximum number of characters to compare. |
| char* SafDupStr | ( | const char * | Str | ) |
Duplicate a string.
Attempts to duplicate a string, allocating the new area and copying the source to it. Returns null if allocation fails. A null input is treated as the empty string.
Freeing the data is the caller's responsibility.
| [in] | Str | String to be copied. |
Definition at line 757 of file saf-env.c.
Referenced by SafModLoad(), SafStoreAdd(), and SafStoreLoad().
| SafRet SafAllocStore | ( | struct SafStore ** | StoreP | ) |
Create a store.
A factory for associative stores. The caller defines a variable of type "pointer to struct SafStore" (an opaque structure) and passes its address to SafAllocStore:
struct SafStore *MyStore = NULL; SafRet Ret; Ret = SafAllocStore(&MyStore); if (Ret) // handle error...
| [out] | StoreP | Pointer to a pointer to a struct SafStore which will receive the address of the newly-created store. |
Definition at line 610 of file saf-store.c.
References SafIsMT(), SafR_OK, SafR_PARAM, and SafR_RESOURCE.
Referenced by EsmParseConfig().
| SafRet SafFreeStore | ( | struct SafStore * | Store | ) |
Free a store and the class and name data in it.
Free a store, including freeing the internal data structures and the class and name data. The store must not be used after this function has been called.
| [in] | Store | The store to be freed. |
Definition at line 671 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
Referenced by EsmParseConfig().
| SafRet SafClearStore | ( | struct SafStore * | Store | ) |
Remove all the data from a store.
Free the data in a store and reset it to its pristine state without reallocating or freeing the store itself or its mutex. This allows a store to be safely cleaned out while it may be in use by other threads.
| [in] | Store | The store to be cleared. |
Definition at line 735 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
| SafRet SafStoreRemove | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name | |||
| ) |
Remove an entry from a store.
| [in] | Store | The store |
| [in] | Class | Class of the value to be removed |
| [in] | Name | Name of the value to be removed |
Definition at line 804 of file saf-store.c.
References SafR_PARAM.
Referenced by SafStoreLoad().
| SafRet SafStoreIterate | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| SafRet(*)(const char *Class, const char *Name, void *Value, void *Data) | Visitor, | |||
| void * | Data, | |||
| SafRet * | VisitorErrP | |||
| ) |
Iterate over a store, optionally filtering for a single class.
Iterate through the given store, calling the supplied visitor function on each value. Optionally filter by class. A nonzero return from the visitor ends iteration.
| [in] | Store | The store |
| [in] | Class | An optional class name to restrict the iteration to values belonging to the specified class |
| [in] | Visitor | A callback, invoked for each value |
| [in] | Data | An optional pointer which will be passed to the visitor callback |
| [out] | VisitorErrP | Returns the final error code of the visitor callback |
Definition at line 850 of file saf-store.c.
References SafR_NOMORE, SafR_OK, SafR_PARAM, and SafSTRCMP_CI.
| SafRet SafStoreAdd | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name, | |||
| void * | Pointer | |||
| ) |
Add an entry to a store.
Add an entry to a store using the given class and name. The class and name strings are duplicated (and need not be preserved by the caller). The contents of the pointer being stored are not inspected; they are the caller's responsibility. If a value with the same class and name already exists in the store, it will be silently replaced.
| [in] | Store | The store |
| [in] | Class | Class to store the value under |
| [in] | Name | Name of the value |
| [in] | Pointer | Pointer to be stored |
Definition at line 927 of file saf-store.c.
References SafDupStr(), SafR_NOTFOUND, SafR_OK, SafR_PARAM, and SafR_RESOURCE.
Referenced by SafStoreLoad().
| SafRet SafStoreFind | ( | struct SafStore * | Store, | |
| const char * | Class, | |||
| const char * | Name, | |||
| void ** | PointerP | |||
| ) |
Retrieve an entry from a store.
Locate the entry in the given store with the given class and name, and set the output PointerP parameter to its value.
| [in] | Store | The store |
| [in] | Class | Class of the value to be located |
| [in] | Name | Name of the value to be located |
| [out] | PointerP | Returns the pointer value from the store |
Definition at line 996 of file saf-store.c.
References SafR_OK, and SafR_PARAM.
Referenced by EsmQueryConfig(), and SafQueryCfg().
| SafRet SafStoreLoad | ( | struct SafStore * | Store, | |
| const char * | Text | |||
| ) |
Load a store from structured text.
Parse a string in "ini"-format structured text format, and add entries to a store corresponding to the sections, names, and values contained in it.
The format has name=value pairs, one per line, within sections indicated by a name in square brackets on a separate line (sometimes called a "section tag"). Blank lines and lines beginning with the comment character ; are ignored, and leading and trailing whitespace is removed from names and values.
For example:
[Section One] Alice=1 Bob=2 # A comment [Section Two] Path = /some/series/of/directories a list = apples bananas pears #This = is commented out true = 1=1
The store provided by the caller (which must have been initialized, but need not be empty) will be populated with entries as follows: the section name string (again, leading and trailing whitespace removed) becomes the class for each section, names are entry names, and values are copied into individually-allocated string buffers that become the values in the store entries.
Any name-value pairs that appear before the first section tag will be stored under an empty class (a class of "").
So, given the sample data above:
struct SafStore *Config; extern const char *ConfigData; // points to string shown above void *Bob; // Parse the data into the store SafAllocStore(&Config); SafStoreLoad(Config, ConfigData); // Get value of "Bob" in "Section One" SafStoreFind(Config, "section one", "Bob", &Bob); printf("Bob is %s\n", Bob);
| [out] | Store | The store to update from the parsed text |
| [in] | Text | The ini-format text to be parsed |
Definition at line 1096 of file saf-store.c.
References SafDupStr(), SafR_INVALID, SafR_OK, SafR_PARAM, SafR_RESOURCE, SafStoreAdd(), SafStoreRemove(), and SafSTRING.
Referenced by EsmParseConfig().