safmgr.h File Reference

Detailed Description

ESF Manager Startup and Control definitions.

Data structures and other definitions for the ESF Manager API, used to initialize and control the ESF Manager.

See also:: safmgr.c

Definition in file safmgr.h.

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct SafInit

ESF Manager Initialization Control Block. More...

Defines

#define SafMGR_H

#define SafESM_MAX   8

Maximum number of ESM Modules.

#define SafMGR_API_VER   0

Initial API version.

#define SafENV_CAS   0

Executing under CAS w/o MTO.

#define SafENV_MFDS   (1<< 0)

Executing under MFDS.

#define SafENV_CICS   (1<< 1)

Executing under CAS w/ CICS.

#define SafENV_IMS   (1<< 2)

Executing under CAS w/ IMS.

#define SafENV_JES   (1<< 3)

Executing under CAS w/ IMS.

#define SafENV_SOLO   (1ul<<31)

Executing standalone.

#define SafENV_MTOMASK   0x0eul

Mask for MTO personalities.

#define SafMGR_FAIL_NONE   0

No failure.

#define SafMGR_FAIL_GENERAL   1

Error with no specific code.

#define SafMGR_FAIL_RESOURCE   2

Resource allocation failed.

#define SafMGR_FAIL_MGRCFG   3

Bad ESF Manager configuration.

#define SafMGR_FAIL_LOAD   4

Failure loading ESM Module.

#define SafMGR_FAIL_ESMCFG   5

Bad ESM Module configuration.

#define SafMGR_FAIL_ESMENTRY   100

Bad ESM Module entry.

#define SafMGR_FAIL_ESM   101

Error reported by ESM Module.

#define SafMGR_FAIL_ENV   200

Environment init failure.

#define SafINIT_OK   0

Initialization succeeded.

#define SafINIT_NULL   1

Null pointer passed for the SafInit parameter.

#define SafINIT_VER   2

Incorrect SafInit::Version value.

#define SafINIT_BAD_CB   3

SafInit structure appears to be invalid.

#define SafINIT_ENV   4

Illegal SafInit::Environment value.

#define SafINIT_CFG   5

Null SafInit::Config pointer.

#define SafINIT_CNT   6

Invalid SafInit::ESMCnt value (> SafESM_MAX).

#define SafINIT_ESMCFG   7

Null pointer in SafInit::ESMCfg array.

#define SafINIT_RESRCE   8

Resource unavailable.

#define SafINIT_OTHER   15

Other failure.

#define SafINIT_FAIL   16

Initialization failed; see SafInit::Reason.

#define SafINIT_BADENV   128

Invalid environment.

#define SafINIT_INTERNAL   129

Internal error.

#define SafINIT_MODNAME   130

Problem with ESM Module name.

#define SafINIT_MODLOAD   131

Failure loading ESM Module.

#define SafINIT_ENVFUNC   132

Failure resolving environment function.

#define SafINIT_EXTERNAL   133

An external service (eg auditing) failed.

#define SafTERM_THREAD   0

Thread is terminating.

#define SafTERM_PROCESS   1

Process is terminating.

#define SafTERM_ESF   2

ESF is being terminated but may be restarted.

#define SafSTRCMP(s1, op, s2)   (strcmp((s1),(s2)) op 0)

Wrapper for strcmp that inlines the operator.

#define SafSTRCMP_N(s1, op, s2, n)   (strncmp((s1),(s2),(n)) op 0)

Wrapper for strncmp that inlines the operator.

#define SafSTRCMP_CI(s1, op, s2)   (SafStrcmpCI((s1),(s2)) op 0)

Wrapper for SafStrcmpCI that inlines the operator.

#define SafSTRCMP_CIN(s1, op, s2, n)   (SafStrcmpCIN((s1),(s2),(n)) op 0)

Wrapper for SafStrcmpCIN that inlines the operator.

#define SafDO_STR(x)   #x

#define SafSTRING(x)   SafDO_STR(x)

Macro to convert argument to string.

Enumerations

enum SafRet {
  SafR_OK = 0, SafR_PARAM = 1, SafR_RESOURCE = 2, SafR_EXFAIL = 3,
  SafR_STATE = 4, SafR_INTERNAL = 5, SafR_NOTFOUND = 6, SafR_TRUNCATED = 7,
  SafR_NOMORE = 8, SafR_INVALID = 9, SafR_ESM = 10, SafR_END = 11,
  SafR_Invalid, SafR_Sizer = (1<<30)
}

ESF Manager API Return Codes. More...

Functions

mf_uns32 safmgr (struct SafInit *Init)

ESF Manager Initialization.

mf_uns32 safterm (mf_uns32 What, void *Reserved)

ESF Manager Termination.

mf_uns32 SafNative32u (mf_uns32 NetValue)

int SafState (void)

ESF Manager Run State.

SafRet SafQueryCfg (const char *Class, const char *Name, char **ValueP)

Query ESF Manager Custom Configuration.

Define Documentation

#define SafESM_MAX 8

Maximum number of ESM Modules.

The ESF Manager supports multiple ESM Modules. Up to this many may be configured for an application (ES region or MFDS).

Definition at line 730 of file safmgr.h.

Referenced by SafAdmin(), and safmgr().

#define SafSTRCMP	(	s1,
		op,
		s2	)	(strcmp((s1),(s2)) op 0)

Wrapper for strcmp that inlines the operator.

Invoke as eg

 if (SafSTRCMP(foo, !=, bar))

Definition at line 1021 of file safmgr.h.

Referenced by SafModLoad(), SafModUnload(), and SafVerify().

#define SafSTRCMP_N	(	s1,
		op,
		s2,
		n	)	(strncmp((s1),(s2),(n)) op 0)

Wrapper for strncmp that inlines the operator.

Like SafSTRCMP(), but with a maximum comparison length as per strncmp().

Definition at line 1029 of file safmgr.h.

#define SafSTRCMP_CI	(	s1,
		op,
		s2	)	(SafStrcmpCI((s1),(s2)) op 0)

Wrapper for SafStrcmpCI that inlines the operator.

Like SafSTRCMP(), but case-insensitive.

Definition at line 1037 of file safmgr.h.

Referenced by SafStoreIterate(), and SafVerify().

#define SafSTRCMP_CIN	(	s1,
		op,
		s2,
		n	)	(SafStrcmpCIN((s1),(s2),(n)) op 0)

Wrapper for SafStrcmpCIN that inlines the operator.

Like SafSTRCMP_N(), but case-insensitive.

Definition at line 1045 of file safmgr.h.

Enumeration Type Documentation

enum SafRet

ESF Manager API Return Codes.

These return codes are used by the public functions in the ESF Manager API. Zero is success and positive values are used for various error conditions.

Enumerator:

SafR_OK	Success.
SafR_PARAM	Invalid parameter value.
SafR_RESOURCE	Required resource not available.
SafR_EXFAIL	External facility (eg OS, RTS) failed.
SafR_STATE	Wrong state for performing operation.
SafR_INTERNAL	Unexpected internal error.
SafR_NOTFOUND	Requested object not found.
SafR_TRUNCATED	Data was truncated.
SafR_NOMORE	End of data reached.
SafR_INVALID	Invalid data encountered.
SafR_ESM	ESM Module or ESM failed.
SafR_END	An operation is being terminated.

Definition at line 979 of file safmgr.h.

Function Documentation

mf_uns32 safmgr ( struct SafInit * Init )

ESF Manager Initialization.

This function must be invoked before any other ESF Manager functions are used.

After successful initialization, a subsequent initialization has no effect. If initialization fails, it can be retried after the problem has been corrected.

Warning:: This function is not thread-safe. It must not be called by multiple threads until after initialization has completed successfully (at which point it will have no further effect).

Parameters:

Init

A pointer to struct SafInit. On entry the following fields must be set:

Version Set to SafMGR_API_VER.
Environment Set to one of the predefined values.
Config Pointing to the ESF Manager configuration block.
ESMCnt Set to the number of configured ESM Modules.
ESMCfg Pointing to configuration blocks for ESM Modules.

On return, ESF Manager will have set Reason and Detail. They will be zero for success, non-zero for error. If a failure occurred in an ESM Module's initialization (see the description for SafInit::Detail), ESMCnt will be set to the index (from 0) of the ESM Module that reported the error.

Returns:: An integer value, zero for success and non-zero if initialization failed. See ESF Manager Initialization Return Codes.

Definition at line 163 of file safmgr.c.

References SafInit::Config, SafInit::ESMCfg, SafInit::ESMCnt, SafESM_MAX, SafINIT_BAD_CB, SafINIT_CFG, SafINIT_CNT, SafINIT_ESMCFG, SafINIT_NULL, SafINIT_OK, SafINIT_VER, SafMGR_API_VER, and SafInit::Version.

mf_uns32 safterm	(	mf_uns32	What,
		void *	Reserved
	)

ESF Manager Termination.

This function should be called when a thread or process that has used ESF is terminating. It will inform the ESM Modules (currently for process exit only), and will perform any necessary cleanup for the Manager itself, including environment-specific cleanup.

Parameters:

`[in]`	What	Indicates what is terminating; see "What" Codes for safterm()
	Reserved	Reserved for future use (pass a null pointer)

Returns:: An integer value, zero for success, non-zero for error. Currently no specific error codes are defined.

Definition at line 538 of file safmgr.c.

References SafEsmExit(), SafEsmUnload(), SafRaiseAuditEvent(), SafTERM_ESF, SafTERM_PROCESS, SafThrLock(), and SafThrUnlock().

int SafState ( void )

ESF Manager Run State.

Returns the run state of ESF Manager (uninitialized, running, terminated).

No parameters

Returns:

An integer value:

0: ESF Manager has not been initialized
1: ESF Manager is running
2: ESF Manager has been terminated

Definition at line 597 of file safmgr.c.

Referenced by SafAdmin(), SafAuth(), SafUpdate(), SafVerify(), and SafXauth().

SafRet SafQueryCfg	(	const char *	Class,
		const char *	Name,
		char **	ValueP
	)

Query ESF Manager Custom Configuration.

MFDS provides a "Configuration Information" text area in each Security Manager configuration object. This area can be used to set custom configuration attributes in "ini" format, with name=value pairs grouped under section headings in square brackets.

This function can be used to query the value associated with a name in a given section.

Parameters:

`[in]`	Class	Section heading (without the brackets)
`[in]`	Name	Item name
`[out]`	ValueP	Returned pointer to value, if any

Returns:: Zero for success or a SafRet value for failure.

Definition at line 621 of file safmgr.c.

References SafStoreFind().

Referenced by SafAdmin(), and SafVerify().


Data Structures
struct	SafInit
	ESF Manager Initialization Control Block. More...
Defines
#define	SafMGR_H
#define	SafESM_MAX 8
	Maximum number of ESM Modules.
#define	SafMGR_API_VER 0
	Initial API version.
#define	SafENV_CAS 0
	Executing under CAS w/o MTO.
#define	SafENV_MFDS (1<< 0)
	Executing under MFDS.
#define	SafENV_CICS (1<< 1)
	Executing under CAS w/ CICS.
#define	SafENV_IMS (1<< 2)
	Executing under CAS w/ IMS.
#define	SafENV_JES (1<< 3)
	Executing under CAS w/ IMS.
#define	SafENV_SOLO (1ul<<31)
	Executing standalone.
#define	SafENV_MTOMASK 0x0eul
	Mask for MTO personalities.
#define	SafMGR_FAIL_NONE 0
	No failure.
#define	SafMGR_FAIL_GENERAL 1
	Error with no specific code.
#define	SafMGR_FAIL_RESOURCE 2
	Resource allocation failed.
#define	SafMGR_FAIL_MGRCFG 3
	Bad ESF Manager configuration.
#define	SafMGR_FAIL_LOAD 4
	Failure loading ESM Module.
#define	SafMGR_FAIL_ESMCFG 5
	Bad ESM Module configuration.
#define	SafMGR_FAIL_ESMENTRY 100
	Bad ESM Module entry.
#define	SafMGR_FAIL_ESM 101
	Error reported by ESM Module.
#define	SafMGR_FAIL_ENV 200
	Environment init failure.
#define	SafINIT_OK 0
	Initialization succeeded.
#define	SafINIT_NULL 1
	Null pointer passed for the SafInit parameter.
#define	SafINIT_VER 2
	Incorrect SafInit::Version value.
#define	SafINIT_BAD_CB 3
	SafInit structure appears to be invalid.
#define	SafINIT_ENV 4
	Illegal SafInit::Environment value.
#define	SafINIT_CFG 5
	Null SafInit::Config pointer.
#define	SafINIT_CNT 6
	Invalid SafInit::ESMCnt value (> SafESM_MAX).
#define	SafINIT_ESMCFG 7
	Null pointer in SafInit::ESMCfg array.
#define	SafINIT_RESRCE 8
	Resource unavailable.
#define	SafINIT_OTHER 15
	Other failure.
#define	SafINIT_FAIL 16
	Initialization failed; see SafInit::Reason.
#define	SafINIT_BADENV 128
	Invalid environment.
#define	SafINIT_INTERNAL 129
	Internal error.
#define	SafINIT_MODNAME 130
	Problem with ESM Module name.
#define	SafINIT_MODLOAD 131
	Failure loading ESM Module.
#define	SafINIT_ENVFUNC 132
	Failure resolving environment function.
#define	SafINIT_EXTERNAL 133
	An external service (eg auditing) failed.
#define	SafTERM_THREAD 0
	Thread is terminating.
#define	SafTERM_PROCESS 1
	Process is terminating.
#define	SafTERM_ESF 2
	ESF is being terminated but may be restarted.
#define	SafSTRCMP(s1, op, s2) (strcmp((s1),(s2)) op 0)
	Wrapper for strcmp that inlines the operator.
#define	SafSTRCMP_N(s1, op, s2, n) (strncmp((s1),(s2),(n)) op 0)
	Wrapper for strncmp that inlines the operator.
#define	SafSTRCMP_CI(s1, op, s2) (SafStrcmpCI((s1),(s2)) op 0)
	Wrapper for SafStrcmpCI that inlines the operator.
#define	SafSTRCMP_CIN(s1, op, s2, n) (SafStrcmpCIN((s1),(s2),(n)) op 0)
	Wrapper for SafStrcmpCIN that inlines the operator.
#define	SafDO_STR(x) #x
#define	SafSTRING(x) SafDO_STR(x)
	Macro to convert argument to string.
Enumerations
enum	SafRet { SafR_OK = 0, SafR_PARAM = 1, SafR_RESOURCE = 2, SafR_EXFAIL = 3, SafR_STATE = 4, SafR_INTERNAL = 5, SafR_NOTFOUND = 6, SafR_TRUNCATED = 7, SafR_NOMORE = 8, SafR_INVALID = 9, SafR_ESM = 10, SafR_END = 11, SafR_Invalid, SafR_Sizer = (1<<30) }
	ESF Manager API Return Codes. More...
Functions
mf_uns32	safmgr (struct SafInit *Init)
	ESF Manager Initialization.
mf_uns32	safterm (mf_uns32 What, void *Reserved)
	ESF Manager Termination.
mf_uns32	SafNative32u (mf_uns32 NetValue)
int	SafState (void)
	ESF Manager Run State.
SafRet	SafQueryCfg (const char Class, const char Name, char **ValueP)
	Query ESF Manager Custom Configuration.