SafInit Struct Reference

ESF Manager Initialization Control Block. More...

Data Fields

mf_uns32 Version
 API version (SafMGR_API_VER).
mf_uns32 Environment
 Execution environment (ESF Manager Execution Environments).
mf_uns32 Reason
 [out] Failure reason code
mf_uns32 Detail
 [out] Failure detail
char ServerName [8]
 ES name under CAS; blank under MFDS.
char Reserved [8]
 Reserved for future use.
int(* CasMsgF )()
 CAS message function.
int(* CasTmpF )()
 CAS table management function.
int(* CasLockF )()
 CAS lock management function.
int(* FailAudit )(const struct safpb_parameter_block *)
 Environment auditor callback.
struct cas_saf_config_internal * Config
 ESF Manager configuration block.
mf_uns32 ESMCnt
 Number of configured ESM Modules; on return, may be index to failing module (see SafInit::Detail).
struct cas_esm_config_internal * ESMCfg [SafESM_MAX]
 ESM Module configuration blocks.

Detailed Description

ESF Manager Initialization Control Block.

A pointer to this structure is passed to the ESF Manager initialization function safmgr(). It provides the ESF Manager with information about the environment in which it's running and its configuration; on return, it reports detailed error information if ESF Manager was unable to start successfully.

Structure versions:

The equivalent COBOL definition: 

78  78-esi-ESM-max           value 8.
01  esi-external-security-init.
    03  esi-api-ver          pic x(4) comp-5 value 1.
        88  esi-api-curr-88  value 1.
    03  esi-env              pic x(4) comp-5.
        88  esi-env-cas-88   value 0.
        88  esi-env-mfds-88  value 1.
        88  esi-env-solo-88  value h'80000000'.
    03  esi-reason           pic x(4) comp-5.
        88  esi-reason-none-88        value 0.
        88  esi-reason-general-88     value 1.
        88  esi-reason-resource-88    value 2.
        88  esi-reason-mgrcfg-88      value 3.
        88  esi-reason-load-88        value 4.
        88  esi-reason-esmcfg-88      value 5.
        88  esi-reason-esmentry-88    value 100.
        88  esi-reason-esm-88         value 101.
        88  esi-reason-env-88         value 200.
    03  esi-detail           pic x(4) comp-5.
    03  esi-server-name      pic x(8).
    03                       pic x(8). *> reserved
    03  esi-service-primitives.
        05  esi-CAS-message-pptr        procedure-pointer.
        05  esi-CAS-service-pptr        procedure-pointer.
        05  esi-CAS-lockmgr-pptr        procedure-pointer.
    03  es-failure-audit     procedure-pointer.         
    03  esi-cfg-ptr          pointer.
    03  esi-ESM-cnt          pic x(4) comp-5.
    03  esi-ESM-cfg-ptr      pointer occurs 78-esi-ESM-max times.

Field Documentation

mf_uns32 Reason

[out] Failure reason code

See the discussion of the Detail field for more discussion of some of the reason codes and additional information that is supplied with them.

See also:
ESF Manager Failure Reason Codes

Referenced by SafEsmInit(), and safmgr().

mf_uns32 Detail

[out] Failure detail

If ESF Manager initialization fails, when safmgr() returns it will set a reason code in the SafInit::Reason field. It may also set this Detail field to provide additional information. The value of the Detail field depends on the reason code. The Manager may also set the ESMCnt field to indicate that the error was produced during intialization of an ESM Module, in which case ESMCnt is set to the index (from 0) of the module that returned the error.

Failure reason codes with additional information
SafMGR_FAIL_ENV
Detail will be the return code from the Processing Environment component.
SafMGR_FAIL_ESM
ESMCnt will be the index of the ESM Module that reported an error, and Detail will be the error code it returned from its Init procedure.
SafMGR_FAIL_ESMCFG
This error indicates that ESF Manager could not load an ESM Module because its configuration is invalid; ESMCnt is the index of the invalid module.
SafMGR_FAIL_ESMENTRY
This error indicates that an ESM Module's initial entry point did not return a proper procedure table; ESMCnt is the index of the invalid module.
SafMGR_FAIL_LOAD
ESMCnt will be the index of the ESM Module that failed to load.

Referenced by SafEsmInit(), and safmgr().

int(* CasMsgF)()

CAS message function.

CAS passes a pointer to its message function when it initializes ESF Manager. Under MFDS, this is void; ESF Manager resolves the necessary MFDS functions by name.

Note that ESF will call this during initialization, so if it points back into the calling module, the calling module must support reentry. (For COBOL, this generally means having local-storage or otherwise supporting recursion.)

Referenced by SafEsmInit().

int(* CasTmpF)()

CAS table management function.

CAS passes a pointer to its table management function when it initializes ESF Manager. Under MFDS, this is void; ESF Manager resolves the necessary MFDS functions by name.

ESF does not currently call this during initialization, but it may in the future, and some ESM Modules call it during their initialization.

Referenced by SafEsmInit().

int(* CasLockF)()

CAS lock management function.

CAS passes a pointer to its lock management function when it initializes ESF Manager. Under MFDS, this is void; ESF Manager resolves the necessary MFDS functions by name.

This is also called during initialization.

Referenced by SafEsmInit().

int(* FailAudit)(const struct safpb_parameter_block *)

Environment auditor callback.

The environment (that is, whatever is calling safinit) can optionally specify a callback function which will be invoked after every security failure: when a Verify call rejects a user's credentials, an Auth call returns an unauthorized status, etc. The callback receives a copy of the final ESF parameter block, including request parameters and status codes. (It should not change anything in the parameter block.)

The callback should return 0. Other return values may be defined in the future.

Referenced by SafProcInit().

The documentation for this struct was generated from the following file: