ESF: safpb_parameter_block Struct Reference

Detailed Description

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);

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).

Definition at line 455 of file safapi.h.


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

safpb_parameter_block Struct Reference

Detailed Description

Data Fields