Macros
#define	SCACC_OK 1
	Constant used to indicate successfull completion of a SCA API function invocation.

#define	SCACC_ERROR -1
	Constant used to indicate unsuccessfull completion of a SCA API function invocation (technical error).

#define	SCACC_FAULT 0
	Constant used to indicate unsuccessfull completion of a SCA API function invocation (business error).

Typedef Index
typedef token_t *	SCAREF
	Pointer to a token_t struct containing details for a resolved and instantiated service reference.

Function Index
void	SCAGetReference (char referenceName, SCAREF referenceToken, int compCode, int reason)
	Resolves and prepares a service reference by name. More...

void	SCAInvoke (SCAREF referenceToken, char opName, int inputMsgLen, void inputMsg, int outputMsgLen, void outputMsg, int compCode, int *reason)
	Performs a service invocation on a previously resolved service reference. More...

void	SCASetFaultMessage (char serviceName, char operationName, char faultName, int bufferLen, void buffer, int compCode, int reason)
	Function to set a fault response from a service implementation component. More...

void	SCAGetFaultMessage (SCAREF token, int bufferLen, char faultName, void buffer, int compCode, int reason)
	Retrieves the fault name and details of the most recently occured fault during service invocation on the specified service reference, if any. More...

Function Details

void SCAGetReference	(	char *	referenceName,
		SCAREF *	referenceToken,
		int *	compCode,
		int *	reason
	)

Resolves and prepares a service reference by name.

The name is resolved among the references declared for the component for/from which resolution is performed.

Parameters

compCode	pointer to a completion code populated with a status code on return; points to `SCACC_OK` on successfull resolution, `SCACC_ERROR` otherwise
reason	not used

void SCAInvoke	(	SCAREF	referenceToken,
		char *	opName,
		int	inputMsgLen,
		void *	inputMsg,
		int	outputMsgLen,
		void *	outputMsg,
		int *	compCode,
		int *	reason
	)

Performs a service invocation on a previously resolved service reference.

Parameters

opName	name of operation to invoke
inputMsgLen	length of request parameter struct in bytes, if this is 0, and `inputMsg` is not 0, `inputMsg` is treated as SDO dataobject; note this is the only supported mode of operation
inputmsg	pointer to service-specific request parameter struct, or to a SDO dataobject
outputMsgLen	length of response parameter struct in bytes; if this is 0, and `inputMsg is not 0`, `inputMsg` is treated as SDO `DATAOBJECT`; note this is the only supported mode of operation
compCode	location of completion code set to `SCACC_OK` or `SCACC_ERROR` or `SCACC_FAULT` on return; if set to `SCACC_FAULT` on return, a business fault may be retrievable using `SCAGetFaultMessage()`
reason	not used

void SCASetFaultMessage	(	char *	serviceName,
		char *	operationName,
		char *	faultName,
		int	bufferLen,
		void *	buffer,
		int *	compCode,
		int *	reason
	)

Function to set a fault response from a service implementation component.

Once SCASetFaultMessage() is invoked from within a component in response to a service invocation, the invocation will result in a fault response, with the response codes and messages populated as described below.

A fault message is supplied as a SDO dataobject. The dataobject to supply is modelled after a SOAP fault detail (and will be incorporated into a fault response as child of the detail (for SOAP 1.1) or Detail (for SOAP 1.2) element). If the fault dataobject has the properties faultcode and/or faultstring, these are interpreted specially as follows. Note that faultcode and faultstring are components of a SOAP fault element rather than a detail element (which is a child element of a fault element), but are interpreted special if they occur on the fault dataobject (representing a detail element) nevertheless.

Use this as follows:

int compcode, reason;

DATAOBJECT faultResponse = doAlloc(df,
    "http://www.w3.org/2001/XMLSchema",
    "anyType");

setCStringByName(faultResponse,
    "faultstring",
    "...");         // application-specific error message

setCStringByName(faultResponse,
    "faultcode",
    "soap:Client"); // or "soap:Server"; the runtime
                    // will interpret the string "Client"
                    // special when occuring in faultcode

SCASetFaultMessage(
    "...",          // service name; can be left empty
    "...",          // operation name; can be left empty
    "...",          // fault name (as in WSDL); can be left empty
    0,
    faultResponse,
    &compcode,
    &reason);

Note the properties faultcode and faultstring, and the special interpretation of the string "Client" are used irrespective of whether SOAP 1.1, SOAP 1.2, or POX/POJSON/REST is being used (even though in the SOAP 1.2 protocol a faultcode-equivalent semantics is represented by the `soapenv:Code/soapenv:Value" element with permitted value "Sender" and "Receiver", respectively, reflecting the broader scope of SOAP 1.2 with respect to eg. spanning multiple TCP request/response cycles).

For SOAP 1.1 invocations, the fault message (as of faultstring) will be included in the faultstring element of the SOAP fault response, and the faultcode will be populated from the faultcode property (ie. faultstring and faultcode will be returned to the client as set in the buffer dataobject).

For SOAP 1.2 invocations, the `soapenv:Reason/soapenv:Text' element will contain the value of the faultstring property, and the soapenv:Code/soapenv:Value element will contain soapenv:Sender if the faultcode property value contains the string Client, and soapenv:Receiver otherwise.

For either SOAP variants, the HTTP 500 error status is returned on a fault.

For REST or POX/POJSON invocations,

if the faultcode property is present, and it contains the string "Client", the HTTP 404 error status is returned to indicate a generic client-side error
otherwise, the HTTP 500 generic server-side error status is returned

Parameters

serviceName	ignored
operationName	ignored
faultName	ignored
bufferLen	must be 0
buffer	must contain an SDO `DATAOBJECT` pointer; the dataobject's `faultstring` property will be examined for the fault message to use in fault responses to an invoker; if no `faultstring` property is set on the dataobject, a generic error message will be responded with instead
compCode	not used
reason	not used

void SCAGetFaultMessage	(	SCAREF	token,
		int *	bufferLen,
		char **	faultName,
		void *	buffer,
		int *	compCode,
		int *	reason
	)

Retrieves the fault name and details of the most recently occured fault during service invocation on the specified service reference, if any.

This function is invoked by a service consumer to get at a fault generated/received by a service implementation (such as by calling SCASetFaultMessage() for an invocation of a SCA service), after SCAInvoke() indicated that a business fault occurred on the respective service reference instance.

For sgmljs.net SCA, it is valid to supply the value 0 as buffer parameter, in which case only faultName gets retrieved.

Parameters

token	the SCAREF through which the service generating a fault was invoked
bufferLen	must be 0
faultName	pointer to a string containing the fault name after call to `SCAGetFaultMessage()`
buffer	`DATAOBJECT` to contain the business fault
compCode	pointer to completion code; will contain `SCACC_OK` after successfull retrieval of a business fault and/or fault name, `SCACC_ERROR` otherwise
reason	not used

SCA

Service API

Macros

Typedef Index

Function Index

Function Details