The ESF Manager runs in two rather different environments: in ES SEP processes under CAS, and in MFDS. In the former it's running in a collection of single-threaded processes communicating via shared memory and with an extensive collection of support routines provided by the COBOL RTS and CAS. In the latter, it's running in a single multi-threaded process and mostly using low-level OS and CCI services (though here too it uses the COBOL RTS for some functions). There are also differences in logging mechanisms and so forth.
This module provides a set of cover routines that the Manager and the ESM Modules it loads can use for various environmental-specific functions.
Definition in file saf-env.c.
Go to the source code of this file.
Defines | |
| #define | snprintf SafSnprintf |
| #define | vsnprintf SafVSnprintf |
| #define | SafNX_VER "4.0" |
| #define | SafNX_KEY "Setup" |
| #define | BUF_SPACE sizeof MsgBuf - (BufPtr - MsgBuf) |
Typedefs | |
| typedef void * | cobdlhandle |
Functions | |
| cobrtncode_t | cobdlload (int, const char *, cobdlhandle *) |
| cobrtncode_t | cobdlgetsym (int, cobdlhandle, const char *, PFI *) |
| cobrtncode_t | cobdlunload (cobdlhandle) |
| mf_uns32 | SafEnvInit (struct SafInit *Init) |
| ESF Environment Initialization. | |
| SafRet | SafModLoad (const char *ModPath, struct SafPTab *(**Entry)(void)) |
| Load a module. | |
| SafRet | SafModUnload (const char *ModPath) |
| Unload a module. | |
| int | SafStrcmpCI (const char *Str1, const char *Str2) |
| Case-insensitive string comparison. | |
| int | SafStrcmpCIN (const char *Str1, const char *Str2, size_t Len) |
| Case-insensitive string comparison (length-limited). | |
| char * | SafDupStr (const char *Str) |
| Duplicate a string. | |
| SafRet | SafShmOpen (const char *Name, size_t *Size, void **Area) |
| Open named "shared" memory. | |
| SafRet | SafGetInstPath (char *Path, size_t MaxLen) |
| Get product installation base path. | |
| int | CBL_NLS_GET_MSG (const char *, const char *, const char *, cbl_nls_msg_params_t *, char *, cbl_nls_msg_ins_struct_t *) |
| SafRet | SafLog (int Num, enum SafMsgLvl Level, 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. | |
| SafRet | SafGetEnvFunc (PFI *FuncP, const char *Name, const char *Env) |
| Resolve environment functions. | |
| int | SafVSnprintf (char *Buffer, size_t BufLen, const char *Format, va_list Args) |
| int | SafSnprintf (char *Buffer, size_t BufLen, const char *Format,...) |
Variables | |
| int | SafCasOldAcee = 0 |
| Old ACEE Format Flag. | |
| 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.
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().
| 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 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().
| 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.
| SafRet SafGetEnvFunc | ( | PFI * | FuncP, | |
| const char * | Name, | |||
| const char * | Env | |||
| ) |
Resolve environment functions.
Search for a named function in the current process. This is used internally by ESF Manager for resolving functions in the MFDS environment, and possibly for other purposes.
| [out] | FuncP | Returned function pointer, a pointer to the PFI (pointer to function returning int) type defined by the COBOL RTS |
| [in] | Name | Function name |
| [in] | Env | Environment name (eg "MFDS"), used for error logging |
Definition at line 1507 of file saf-env.c.
References SafLog(), SafMsgCRIT, SafR_NOTFOUND, and SafR_OK.
Referenced by SafInitAuditing().
| int SafCasOldAcee = 0 |
Old ACEE Format Flag.
For internal use only.
This flag is set if CAS is using the old ACEE format, with the initial SAA structure included.
Definition at line 278 of file saf-env.c.
Referenced by SafVerify().