tpf_srvcInvoke: Call the interface to another application

Use this function to enable one application to make a synchronous service call to another application.

Last updated

  • Changed in 2020.
  • Changed in 2019.
  • Changed for PUT15.
  • Added for PUT14.

Format

LIBS := CSVC
#include <tpf/services.h>

int tpf_srvcInvoke(const char *serviceName, void *request, int 
reqSize, tpf_srvc_resp **response, int flags);
serviceName
A pointer to a unique string identifier that represents the service to be called. The identifier is bound to a z/TPF service descriptor based on the version of the z/TPF service descriptor. For version 1, the identifier must match the operationId element. For version 2, the identifier must match the <basePath>/<operationId> element concatenation.
request
A pointer to the storage that contains the request data that is specified in the request field in the z/TPF service descriptor. Pass NULL if no request data is specified.
reqSize
A value that represents the passed size of data in the request buffer.
response
The address of a pointer that will reference the tpf_srvc_resp structure upon return. The pointer that is referenced will be set to NULL if the tpf_srvc_resp structure is not allocated and returned. The service response information is described by the tpf_srvc_resp typedef and has the following fields:
data
The response data that is specified in the response field in the z/TPF service descriptor.
datalen
The size of the response data.
status
A positive integer value that depends on the type of services.
status_reason
A pointer to a string that represents extra information about the status code from a normal return.
The tpf_srvcInvoke function processing allocates storage for the response in the ECB heap. The calling application is responsible for releasing this storage when the storage is returned.
flags
Flags that are reserved for future use. You must specify a value of 0.

Normal return

Return value Description
TPF_SRVC_INVOKE_SUCCESS The function is completed successfully.

Error return

Return value Description Errno Description
TPF_SRVC_INVOKE_FAILURE An error occurs during the service call. EINVAL The invalid value that was passed in the flags or response parameter was NULL.
ENOMEM The service operation could not allocate the response buffer.

Programming considerations

  • This function is suspended until the service is fulfilled or an error condition occurs.
  • This function is threadsafe.
  • This function does not support calling services that are defined with the providerType element set to StatefulProgram.

Examples

The following example shows how to set up a request, call the service, and process the results. 
#include <tpf/services.h>

… //existing program logic/function
pricingRequest parms;
tpf_srvc_resp *resp;
pricingResponse *retData;
int rc, flags=0;
double price;

parms.ffid = (unsigned long int) existingAppFFID;
parms.flightData.departDate = existingAppdtime; 
strcpy(parms.flightData.origCity, "JFK";);
parms.flightData.returnDate = existingApprtime;
strcpy(parms.flightData.destCity, "ORD";);
strcpy(parms.addons, "hc mil";);
rc = tpf_srvcInvoke("doPriceLookup", &parms, sizeOf(pricingRequest), &resp,
flags);

if (rc == TPF_SRVC_INVOKE_SUCCESS) {
  if (resp->status == TPF_SRVC_OK) {
    retData = resp->data;
    price = retData->price; //from srcv defined pricingResponse
  }
 else {  // service application returned error
    printf("doPriceLookup returned error:  %s",resp->status_reason);
  }
}
else {    // rc=TPF_SRVC_INVOKE_FAILURE
    printf("tpf_srvcInvoke returned failure errno %d",errno);

}
if (resp) { free(resp); }
return;
The following example shows how to call a service that is associated with a version 2 z/TPF service descriptor.
#include <tpf/services.h>

…  //existing program logic/function
srvcRequest1 parms;
tpf_srvc_resp *resp = NULL;
default_resp *retData;
int rc;

rc = tpf_srvcInvoke("/sample/srvcReq1v2/sampleSrvc", &parms, sizeof(parms), &resp, 0);

if (rc == TPF_SRVC_INVOKE_SUCCESS) {
  if (resp->status == TPF_SRVC_OK) {
    retData = resp->data;
  }
 else {  // service application returned error
    printf("sampleSrvc returned error:  %s",resp->status_reason);
  }
}
else {    // rc=TPF_SRVC_INVOKE_FAILURE
    printf("tpf_srvcInvoke returned failure errno %d",errno);
}
if (resp) { free(resp); }
return;