safpb_parameter_block Struct Reference

ESF "SAFROUTE" API Parameter Block. More...

Data Fields
mf_uns32	safpb_version
	IN ESF API version identifier (saf78_VERSION_1).
mf_uns8	safpb_request
	IN request code (ESF API Request Codes).
mf_uns8	safpb_type
	IN request qualifier (ESF API Request Qualifiers).
mf_uns8	safpb_modifier
	IN subsystem identifier (ESF API Subsystem Identifiers).
mf_uns8	safpb_flag
	IN flag byte (ESF API Request Flags).
mf_uns16	safpb_codeset
	IN character set identifier (ESF API Character Codesets).
mf_uns8	safpb_availchar1
	available for future use
mf_uns8	safpb_availchar2
	available for future use
union {
mf_uns8 safpb_api_rc_aggregate [3]
	OUT Return codes as array.
struct safpb_Api_Rc_Aggregate {
mf_uns8 safpb_api_rc
	OUT ESF API return code.
mf_uns8 safpb_mgr_return
	OUT ESF Manager return code.
mf_uns8 safpb_mgr_reason
	OUT ESF Manager reason code.
} DISCRETE
	Discrete return codes.
}	RETCODES
	Return codes; see ESF API Return Codes.
mf_uns8	safpb_safesm_index
	IN/OUT ESM index.
union {
struct safpb_verify VERIFY
	Verify request.
struct safpb_auth AUTH
	Auth request.
struct safpb_xauth XAUTH
	XAuth request.
struct safpb_audit AUDIT
	Audit request.
struct safpb_stat STAT
	Status request.
struct safpb_admin ADMIN
	Admin request.
struct safpb_update UPDATE
	Update notification.
}	REQUESTS
	request-specific areas

Detailed Description

ESF "SAFROUTE" API Parameter Block.

This parameter block is the sole parameter to most of the ESF API calls: Verify, Auth, etc. The caller creates and initializes the parameter block, then passes its address to the SAFROUTE function.

On input the caller should have set the global fields marked "IN" and "IN/OUT", such as safpb_parameter_block::safpb_version, and those fields in the structure associated with the request type (safpb_parameter_block::VERIFY for a Verify call, and so forth).

For example, in C:

   #include "safapi.h"

   Safpb_Parameter_Block VerifyReq = {0};

   VerifyReq.safpb_version = saf78_VERSION_1;
   VerifyReq.safpb_request = saf78_REQUEST_VERIFY;
   VerifyReq.safpb_type    = saf78_TYPE_ENVIR_CREATE;
   VerifyReq.safpb_codeset = saf78_CODESET_UTF8;

   VerifyReq.REQUESTS.VERIFY.safpb_verify_USERID_len = strlen(UserID);
   VerifyReq.REQUESTS.VERIFY.safpb_verify_PWRD_len   = strlen(Password);
   VerifyReq.REQUESTS.VERIFY.safpb_verify_USERID_ptr = UserID;
   VerifyReq.REQUESTS.VERIFY.safpb_verify_PWRD_ptr   = Password;

   SAFROUTE(&VerifyReq);

or in COBOL:

       data division.
       working-storage section.
       copy 'safapi.cpy' replacing ==()== by ==ws==.

       procedure division.
       call-verify.
      *    Set up ESF request parameter block
           move low-values to ws-safpb-parameter-block
           set ws-safpb-cur-ver-88 to true
           set ws-safpb-verify-req-88 to true
           set ws-safpb-verify-create-88 to true
           set ws-safpb-codeset-utf8-88 to true

      *    Set up ESF Verify parameters
           move UserID-Length to ws-safpb-verify-USERID-len
           set ws-safpb-verify-USERID-ptr
               to address of UserID
           move Password-Length to ws-safpb-verify-PWRD-len
           set ws-safpb-verify-PWRD-ptr
               to address of Password

      *    Make the call
      *    Set the error code to 04/32/00 if security is not enabled.
           call "SAFROUTE" using ws-safpb-parameter-block
               on exception move x'042000' to ws-safpb-api-rc-aggregate
           end-call
           .

On return, the fields marked "OUT" and "IN/OUT" will have been populated by ESF Manager, for a successful call. If an error occurred, some fields may not have been populated.

There are three fields for returning error information:

safpb_parameter_block::safpb_api_rc is the ESF API return code, which signals overall success or failure.
safpb_parameter_block::safpb_mgr_return is the return code set by ESF Manager or the ESM Module which signalled a failure. It contains a more-specific error value which indicates what subtype of failure occurred. Note these values are only unique for a given ESF API return code.
safpb_parameter_block::safpb_mgr_reason is a reason code which provides more detail on the error condition.

Various combinations of API return code, manager return code, and reason code are listed in ESF API Return Codes.

If an ESM Module triggered the failure, the safpb_parameter_block::safpb_safesm_index field will be set to the index, starting from 1, of the failing module in the ESM Module list configured for the failing component (ES server or MFDS).

If the saf78_FLAG_TRACE bit is set in safpb_parameter_block::safpb_flag, optional trace messages will be turned on in ESF and some of the ESM Modules. These messages are output through the normal ESF logging mechanism for the environment in which ESF is running (for example, the CAS console log for ESF requests in emulated mainframe applications).

If the saf78_FLAG_API_DISPLAY bit is set in safpb_parameter_block::safpb_flag, some tracing information will be written to stdout. This is generally only useful for command-line programs.

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

safapi.h

safpb_parameter_block Struct Reference

Data Fields

Detailed Description