NonStop SOAP 4.1 User's Manual
NonStop SOAP 4.1 User's Manual
HP Part Number: 532118-006
Published: April 2014
Edition: J06.09 and subsequent J-series RVUs and H06.20 and subsequent H-series RVUs.
For example, if you specified $DATA.MATH as the dictionary location in the mathddl file, successful compilation of mathddl generates the following files in the $DATA.MATH location: oss> exit GUARDIAN> volume $DATA.MATH $DATA.
2. Update the following attributes in the mathsdl.xml file: • Url Verify the Url attribute of the sdl element. This attribute must have a Web address pattern. For example, Url= “/mytest” where, "/mytest" is the Web address pattern entered while creating the NonStop SOAP 4 deployment directory by running the deploy.sh deployment script. For more information, see Step 6 in “Setting up the Deployment Environment” (page 38).
•
For example: OSS> export PATH=/usr/tandem/nssoap/t0865h01/tools:$PATH where, /usr/tandem/nssoap/t0865h01 is the NonStop SOAP 4 installation directory. 3. Add the
5. On successful execution, the following service skeleton files are generated: • The NonStop SOAP 4 skeleton source file, where the axis2_svc_skeleton interface functions are implemented • The service skeleton source file, where you must implement the business logic for your application • Header file for the service skeleton file For example, for the math service, the following files are generated in the
In case of the math service, the libmath.so file and the services.xml file must be located in the
2. Enter the values for the two parameters to be added, and then click submit. For example: param1 : 20 param2 : 30 On successful submission, the following result appears in the Web browser: - 6 NonStop SOAP 4 Client APIs This chapter describes the NonStop SOAP 4 APIs you can use to develop client applications that consume SOAP Web services. This chapter includes the following topics: • “NonStop SOAP 4 Client APIs” (page 105) • “Developing NonStop SOAP 4 Clients Using Client APIs” (page 119) NonStop SOAP 4 Client APIs NonStop SOAP 4 client APIs provide the following stack of function calls to develop client applications that consume SOAP Web services.
NOTE: The axis2_svc_client_create()and axis2_svc_client_free()functions are generated by the WSDL2C tool for NonStop SOAP 4 clients. This tool consumes the WSDL file of the service to generate client stubs which contain the definition for these functions. For more information about the WSDL2C tool, see “NonStop SOAP Tools” (page 194). The axis2_svc_client_create()Function The axis2_svc_client_create() function creates and returns a pointer to the axis2_svc_client_t NonStop SOAP 4 client structure.
The AXIOM APIs that enable you to generate the request AXIOM node and consume the response AXIOM node are described in the following section: • “Generating the Request AXIOM node using NonStop SOAP 4 APIs” (page 107) • “Consuming the Response AXIOM node using NonStop SOAP 4 APIs” (page 111) Generating the Request AXIOM node using NonStop SOAP 4 APIs NonStop SOAP 4 provides APIs to generate the request AXIOM node using one of the following approaches: • “Creating an AXIOM node using AXIOM Node Create AP
child is an input parameter and is a pointer to the child node of type axiom_node_t. It cannot have a NULL value. Return values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure. The axiom_element_create()Function The axiom_element_create()function creates an AXIOM element using the specified name.
attribute is an input parameter and is a pointer to the attribute to be added to the element. It cannot have a NULL value. node is an input parameter and is a pointer to the axiom_node_t node that contains om_element. It cannot have a NULL value. Return values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure. The axiom_attribute_create()Function The axiom_attribute_create()function creates an AXIOM attribute structure.
Return values: Pointer to the AXIOM node created from the XML stream. Creating an AXIOM node from an XML using AXIOM Document APIs If you create the service response AXIOM node from an XML message, use the AXIOM document APIs to create the AXIOM node from the response XML. NOTE: You need not use the AXIOM document APIs if the service builds the response using AXIOM APIs.
Parameters: document is an input parameter and is a pointer to the axiom_document_t structure to be built. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Value: Pointer to the AXIOM node built from the document. If an error occurs, it returns NULL. The axiom_document_free()Function The axiom_document_free()function is used to free the document structure from memory.
om_node is an input parameter and is a pointer to the axiom_node_t node that contains om_element. Return Values: Pointer to the qname of the element. If an error occurs, it returns NULL. The axiom_node_get_data_element()Function The axiom_node_get_data_element()function retrieves the AXIOM element structure from the AXIOM node.
Parameters: element is an input parameter and is a pointer to the element whose attribute must be found. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: Pointer to the attribute with the given qname. If an error occurs, it returns NULL and sets the error code in the environment error structure.
const axutil_env_t * env, const axiom_node_t * payload, axis2_callback_t * callback ) Parameters: svc_client is a pointer to the service client structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. payload is a pointer to the AXIOM node representing the XML payload to be sent. The caller controls the payload until the service client releases it. callback is a pointer to the callback structure used to capture response.
Synopsis: AXIS2_EXTERN void axis2_svc_client_fire_and_forget ( axis2_svc_client_t * svc_client, const axutil_env_t * env, const axiom_node_t * payload ) Parameters: svc_client is a pointer to the service client structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. payload is a pointer to the AXIOM node representing the XML payload to be sent. The caller controls the payload until the service client releases it.
• “The axutil_log_impl_log_debug()Function” (page 116) • “The axutil_log_impl_log_trace()Function” (page 116) The axutil_log_impl_log_warning()Function The axutil_log_impl_log_warning()function logs warning messages in the specified log file. Synopsis: AXIS2_EXTERN void axutil_log_impl_log_warning (axutil_log_t *log, const axis2_char_t *filename, const int linenumber, const axis2_char_t *format,...
ADB APIs for creating requests The WSDL2C with ADB (Axis2) data binding creates getter and setter methods at both schema level and the message level. You can use these APIs to create SOAP requests. You must implement the following functions to develop applications using NonStop SOAP 4 client ADB APIs.
Synopsis: adb_
Developing NonStop SOAP 4 Clients Using Client APIs This section describes the procedure to develop and deploy a NonStop SOAP 4 client using the NonStop SOAP 4 client API. This section describes the procedure to develop a client for the math service. To develop NonStop SOAP 4 clients, use one of the following: • The client API stack The client API stack enables you to develop NonStop SOAP 4 clients manually.
For example: OSS> export PATH=/usr/tandem/java/bin:$PATH where, /usr/tandem/java/ is the Java installation directory. 4.
For example: OSS> WSDL2C -o "
OSS> make The math.exe file is created at
-l /usr/tandem/nssoap/t0865h01/lib/libaxis2_http_sender.so \ -l /usr/tandem/nssoap/t0865h01/lib/libguththila.so 3. Ensure that the services.xml and the service DLL (.so) files are located in the
7 Customizing NonStop SOAP 4 Message Processing NonStop SOAP 4 processes a request based on the default message process. This chapter provides information on customizing the default NonStop SOAP 4 message process using Phases, Modules, Handlers, and Message Receiver User Functions.
Message Receiver User Functions In the NonStop SOAP 4 architecture, a message receiver converts the incoming SOAP request from the NonStop SOAP 4 internal format (AXIOM node) to a format that is compatible with the deployed service. NonStop SOAP 4 supports the following message receivers: • Pathway message receiver: used to invoke services running as Pathway applications or NonStop processes.
Figure 12 Modified Message Process in NonStop SOAP 4 Service Consumer Transport Phase Transport in Phase Handlers Transport in Phase Handlers PreDispatch Phase Handlers PreDispatch Phase Dispatch Phase Handlers Dispatch Phase User Defined Phases User Defined Phase Handlers Post Dispatch Phase Handlers PostDispatch Phase Message Out Phase Message Out Phase Handlers User Defined Phase Handlers UserDefined Phases User Defined Phases User Defined Phase Handlers Pre Service MRUF Message Receiv
Request Processing in NonStop SOAP 4 Request processing in NonStop SOAP 4 takes place through the interaction of the following components: • “Flows” (page 127) • “Phases” (page 128) • “Handlers” (page 130) • “Modules” (page 130) The default message process in NonStop SOAP 4 uses only flows and phases; it does not use handlers and modules. You can customize the default message process using handlers and modules to meet your business requirements.
Phases A Phase is a stage of processing or a time interval in the message process. A collection of phases forms a Flow. The phases within a flow, and the order in which they are invoked, are defined within the phaseOrder element in the axis2.xml configuration file. For more information on the axis2.xml configuration file, see “NonStop SOAP 4 Configuration Files” (page 177). Pre-defined phases in inflow The 1. 2. 3. 4.
The handlers attached to the PostDispatch phase can access the service name and operation name of the target service for which the message is intended after the PostDispatch phase. The handlers in this phase perform the following tasks: • Get/Set the service name • Get/Set the operation name • Update the message context structure PostDispatch This phase verifies if the dispatchers have been able to find a service and an operation for the message.
MessageOut This phase executes the transport handlers from the associated transport configuration. The last handler is always a transport sender that sends the SOAP message to the target endpoint. The handlers attached to the MessageOut phase can access the response message. Handlers attached to this phase perform the following tasks: • Modify the response buffer • Modify the response XML Transport This phase is part of the inflow and outflow.
1. 2. 3. 4. “Running the SoapAdminCL Tool to Generate the Module Handler Stub Files” (page 133) “Implementing the Business Logic in the Module Handler Stub Files” (page 134) “Engaging the Module Handler at the Service Level” (page 136) “Verifying the Module Handler Output” (page 137) Running the SoapAdminCL Tool to Generate the Module Handler Stub Files The SoapAdminCL tool enables you to generate the module handler stub files and the module.xml file.
logging_out_handler.c is the C stub file where you must implement the loggingOutHandler business logic for the handler. For the logging module, the business logic is designed to log the output XML message. Makefile is the Makefile for the logging module. NOTE: If the specified directory is not created with all the listed files, repeat Step 1 through Step 3. Do not attempt to manually create the directory structure or the files in it.
where, axis2_handler *handler is the address of a handler object. const axutil_env_t *env is the address of the environment structure. struct axis2_msg_ctx *msg_ctx is the address of a message context structure. The message context structure includes information about the XML message and the message context. Implement the following business logic for the logging module: 1. Get the SOAP envelope from the message context structure. 2. Get the SOAP message body from the SOAP envelope. 3.
4. Edit the module.xml file as follows: • Set the value of the phase attribute of the order element in the inflow to PostDispatch. The loggingInHandler is invoked in the PostDispatch phase. • Set the value of the phase attribute of the order element in outflow to MessageOut. The loggingOutHandler is invoked in the MessageOut phase.
NOTE: You can engage the module at the global level, which makes the module intercept messages for every service. To engage the module at the global level, add the following entry in the axis2.xml file.
4. “Modifying the Message Flow in the Pathway Message Receiver using NonStop SOAP 4 Message Receiver User Functions” (page 147) Configuring NonStop SOAP 4 Message Receiver User Functions Message Receiver User Functions can be configured in NonStop SOAP 4 at the service level and at the global level.
1. Add the parameter name MessageReceiverUserFunctions under the axisconfig element in the axis2.xml file. The value of the MessageReceiverUserFunctions parameter must be set to the DLL (.so file) class that implements the Message Receiver User Functions:
where, env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: Returns a pointer to the axis2_MessageReviverUserFunction_t structure. If an error occurs, it returns NULL. Setting pre_service and pre_marshal function names After you create a pointer of the Message Receiver User Functions structure, the callback functions that implement the pre_service and pre_marshal functions must be set in the Message Receiver User Functions structure pointer.
const axutil_env_t * env PRE_MARSHAL_FUNCTION func) Parameters: inst is an input parameter and is a pointer to the Message Receiver User Functions structure created using the MessageReceiverUserFunctions_create() function. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. func is an input parameter that holds the name of function that implements the pre_marshal functionality. Return Values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure.
Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. payload is an input parameter and is a pointer to the request message buffer. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. ReqLen is an input parameter and is a pointer to the request length of the buffer. in_msg_ctx is an input parameter and is a pointer to the message context structure for the inflow.
in_msg_ctx is an input parameter and is a pointer to the message context structure for inflow. out_msg_ctx is an input parameter and is a pointer to the message context structure for outflow. Return value: Returns the length of the response message buffer as int. If you are modifying the response buffer in the pre_marshal function, you must modify the length of the response buffer (ResLen) before the returning statement of the pre_marshal function.
Synopsis: AXIS2_EXPORT axis2_char_t *AXIS2_CALL axis2_msg_recv_get_serverclassName( axis2_MessageReceiverUserFunctions_t * MessageReceiverUserFunctions, const axutil_env_t * env) Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value.
Return Value: Returns the value of the operation name as an axis2_char_t pointer. The axis2_msg_recv_get_processName()Function The axis2_msg_recv_get_processName()function returns the value of the process name for the service.
const axutil_env_t * env, const axis2_char_t * serverclass) Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. serverclass is the name of the server class you want to set for the service.
Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. operationName is the operation name you want to set for the service.
Synopsis: AXIS2_EXPORT axis2_bool_t AXIS2_CALL axis2_msg_recv_get_skipService( axis2_MessageReceiverUserFunctions_t * MessageReceiverUserFunctions, const axutil_env_t * env) Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Value: Returns the value of the skipService flag.
Synopsis: AXIS2_EXPORT axis2_status_t AXIS2_CALL axis2_msg_recv_set_skipService( axis2_MessageReceiverUserFunctions_t * MessageReceiverUserFunctions, const axutil_env_t * env, const axis2 bool t * skipService ) Parameters: MessageReceiverUserFunctions is an input parameter and is a pointer to the address of the axis2_MessageReceiverUserFunctions_t structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. skipService is a flag that skips the service.
Developing the Message Receiver User Functions involves the following tasks: 1. “Running the SoapAdminCL Tool to Generate the Message Receiver User Functions Stub Files” (page 150) 2. “Implementing the Business Logic in the Message Receiver User Functions Stub Files” (page 150) 3. “Engaging the Message Receiver User Functions at the Service Level” (page 151) 4.
Implementing the pre_service Message Receiver User Function For the implementation of business logic for the pre_service Message Receiver User Function, see the sample code in the
8 NonStop SOAP 4 Service Description Language The NonStop SOAP 4 SDL file is an XML file that describes the Web services deployed in NonStop SOAP 4. The SDL file along with the data definition language file for the Web service is used as an input by the SoapAdminCL tool to generate the WSDL file, HTML clients, XML schema files, SOAP request and response XML files, and the services.xml file for NonStop SOAP 4 services. NonStop SOAP 4 does not use the SDL file during runtime.
ServerAddress = “http://www.nonstopsoap.com” Generated WSDL file:
PathmonName="$PMON" Generated services.xml file:
DDLDictionaryLocation="$volume.subvolume" NOTE: The DDL dictionary includes the SOAP request and response structures for the particular service. If the dictionary is not available at the specified location, the SoapAdminCL tool reports the following error and ends the operation. SOAPADMIN ERROR >> Error generating files for
type="xsd:string" />
mod_
The Operation element includes the following attributes: • Name • TMFTransactionSupport • AbortTransactionOnFault • NameSpaceQualified • SoapMessageType • ProcessSoapDDLComments • SoapDDLAttribute • OutputFileNamePrefix • UseDDLDefaultValue • EnableOutputSensitive • RspEncoding The Operation element includes the following attributes: Name The Name attribute specifies the name of the operation. The value of this attribute should be unique in a single NonStop SOAP 4 deployment.
. . Generated services.xml file:
SDL file: AbortTransactionOnFault ="yes" Generated services.xml file:
Table 4 The DDL Comments values (continued) DDL Comment Description * @SOAP_OPTIONAL @SOAP_SUPPRESS_OUT input type binary 32. WSDL file translation:
Table 4 The DDL Comments values (continued) DDL Comment Description This generates the
For example: SDL file: SDL file: SoapDDLAttribute ="yes" SoapDDLAttribute ="no" Generated schema in the WSDL file: Generated schema in the WSDL file:
UseDDLDefaultValue="yes" UseDDLDefaultValue="no" DDL File: DDL file: DEFINITION REQ. 10 Request. 20 req1 type character 5 Value "R". 20 req2 type character 5 value "B". 20 req3 type character 2 Value "R". END DEFINITION REQ. 10 Request. 20 req1 type character 5 Value "R". 20 req2 type character 5 value "B". 20 req3 type character 2 Value "R".
?nooutput_sensitive End. Now, compile the DDL using the following command: gtacl -p ddl < "ddl file-name" CAUTION: line. The DDL must not be compiled with the output_sensitive flag in the command RspEncoding The RspEncoding attribute specifies any default output encoding for a Pathway service other than UTF-8. The SOAP request and response XML file reflects the value of this attribute. The default value is UTF-8. This attribute is optional.
The RequestInfo element has a child element named DDLDefinitionName. • The DDLDefinitionName Element The DDLDefinitionName element specifies the DDL definition of the NonStop SOAP 4 request that is accepted by the Pathway service. This is a mandatory element. The element definition appears in the SDL file as: For example: DDL file: DEFINITION REQ. 10 request TYPE character 12. END SDL file:
NOTE: You can use multiple
Generated services.xml file:
Table 6 Comparison Operator Values Table Value Effect eq Response is selected if the Response buffer value between the start and end index matches the value mentioned in the BufVal attribute. gt Response is selected if the Response buffer value between the start and end index is greater than the value mentioned in the BufVal attribute. lt Response is selected if the Response buffer value between the start and end index is less than the value mentioned in the BufVal attribute.
AbortTransactionOnFault="no" NameSpaceQualified="no" SoapMessageType="document" ProcessSoapDDLComments="yes" SoapDDLAttribute="yes" UseDDLDefaultValue="no" EnableOutputSensitive="no">
SrvrEncoding="UTF-8" GenerateSessionHeader="[yes | no]" GenerateTransactionHeader="[yes | no]" GenerateModuleHandlerFiles="[yes | no]" GenerateMessageReceiverUserFunctionsFiles="[yes | no]" stringTermination="[NonNull | NullTerminated]"> The ProcessDetails element includes the following attributes: • Name • DDLDictionaryLocation • language • SrvrEncoding • GenerateSessionHeader • GenerateTransactionHeader • GenerateModuleHandlerFiles • GenerateMessageReceiverUserFunctionsFiles • stringTerm
The ServerAPI Element The ServerAPI element specifies that the service is a server API service. The SDL file can define multiple ServerAPI environments. Multiple environments are separated by the ServerAPI element. The element definition appears in the SDL file as:
9 NonStop SOAP 4 Configuration Files The NonStop SOAP 4 distribution includes configuration files that can be used to configure the NonStop SOAP 4 server, its modules, and the services running under it. This chapter describes the following NonStop SOAP 4 configuration files: • “The itp_axis2.config File” (page 177) • “The axis2.xml File” (page 180) • “The services.xml File” (page 182) • “The module.
NOTE: You must specify the location of the itp_axis2.config file in the
Example 1 A Sample itp_axis2.config Configuration File # # # # # # # i t p _ a x i s 2 . c o n f i g This file resides in / and contains information for the deployment described at /home/usr1/t0865h01 This file was generated by /usr/tandem/nssoap/t0865h01/bin/deploy.
NOTE: The location specified for ICU_DATA must be a valid, existing location containing the ICU files to be used for encoding. If the location does not exist, SOAP server logs an error message. If the files in the given location are missing or corrupt, then encoding features will work only for the UTF-8 encoding type. Defining the Log File Size The NonStop SOAP 4 server supports log and trace file rollover after the files reach a specific size.
class [axis2_pway_receiver | axis2_receivers ] is the Message Receiver class to be attached with NonStop SOAP 4. This is a mandatory attribute. The NonStop SOAP 4 distribution supports the following Message Receivers: axis2_pway_receiver specifies the Pathway Message Receiver to be used for communication with NonStop processes or Pathway services. The default value is axis2_pway_receiver. axis2_receivers specifies the XML Message Receiver to be used for services developed using server APIs.
Specifying the Order of Phase Invocation in NonStop SOAP 4 Message Processing NonStop SOAP 4 enables you to specify the order in which the pre-defined and user-defined phases can be invoked during a message processing cycle. To specify the invocation order of the phases, modify the phaseorder attribute to reflect the desired order of invocation. You can also customize user–defined phases using the phaseOrder attribute.
Updating the Service Parameters The services.xml file is used to set the service parameters to configure a service as a Pathway application, a process, or as a DLL. NOTE: The service parameters are set using the parameter tag and are defined as name-value pairs. You need not modify the service parameters because the services.xml file is generated by the SoapAdminCL tool.
Table 10 Valid AlignmentRule setting for existing COBOL services that use DDL generated header files COBOL option DDL setting AlignmentRule setting Default C00CALIGN even Default CFIELDALIGN_MATCHED2 shared2 Default C_MATCH_HISTORIC_TAL shared2 Default SHARED8 shared8 Table 11 Valid AlignmentRule setting for existing COBOL services that does not use DDL generated header files COBOL option AlignmentRule setting Default even All elements marked as SYNC datatype NOTE: For C and COBOL servi
Defining Multiple SOAP Response Selection Criteria NonStop SOAP 4 enables you to define multiple response messages for each operation in a Web service based on a multiple response selection criterion. The response selection criterion can be defined using the following name attributes of the parameter element in the services.xml configuration file. • TotalResponse This element defines the total number of responses that must be considered while selecting a single response for a given operation.
For example, if the StartIndex is specified for the first response selection criterion, the sample syntax will be:
to” and the default conversion operator is “string”. If the buffers match, the response structure in Response0 is selected to return the response to the client. Controlling TMF Transaction Support NonStop SOAP 4 enables you to specify whether a TMF transaction must be started for a given operation. To achieve this, specify the TMFTransactionSupport parameter in the name attribute of the parameter element in the services.xml file. This is an optional element.
Example 2 A Sample services.xml Configuration File
mep is the MEP Web address to be used for this operation. If not specified, the default MEP Web address is http://www.w3.org/2004/08/wsdl/in-out, which maps to the IN-OUT MEP. Setting the Operation-Specific Message Receiver NonStop SOAP 4 enables you to override the Message Receiver configurations set in the axis2.xml file at the operation level. You can specify the Message Receiver to be invoked by NonStop SOAP 4 for an operation.
on when another handler is invoked. To specify the order of invoking handlers, include the following entry with the required information in the module.xml file:
10 NonStop SOAP Tools The NonStop SOAP 4 distribution includes tools that help perform important tasks, such as: • Generating the WSDL file, the services.
NOTE: • The migration WSDL files are generated only when the -m migration flag is used. • You can generate an SDL file for NonStop SOAP 4 services using the following: ◦ NonStop SOAP 4 Administration Utility ◦ NonStop SOAP 3 SDR file with the NonStop SOAP 4 SoapAdminCL tool ◦ Copying and updating the SDL files distributed with the NonStop SOAP 4 distribution For more information about the SDL file, see “NonStop SOAP 4 Service Description Language” (page 153).
Table 13 Location of Files Generated by the SoapAdminCL Tool File Name Location WSDL
SoapPW_
OSS> SoapAdminCL -i mysdl.xml The generated directory structure appears in the current directory as:
SoapPW_myoperation1.xml SoapPW_myoperation1Response0.xml SoapPW_myoperation2.xml SoapPW_myoperation2Response0.xml /pway-xsd SoapPW_myoperation1.xsd SoapPW_myoperation1Response0.xsd SoapPW_myoperation2.xsd SoapPW_myoperation2Response0.xsd /wsdl SoapPW_myoperation1.wsdl SoapPW_myoperation2.wsdl /services /myservice SoapPW_myservice.wsdl services.xml Generating Module and Handler Stubs To generate the module and handler stubs, use the SoapAdminCL tool with the –mod command line option.
logging.h logging_in_handler.c logging_out_handler.c Makefile Generating Message Receiver User Functions Stubs Message Receiver User Functions (MRUF) enable you to modify the message buffer, Pathway or service attributes, and customize the message flow in the Message Receiver phase. For more information about MRUF, see “Customizing NonStop SOAP 4 Message Processing” (page 124). NOTE: The SoapAdminCL tool can generate MRUF stubs that can be customized as required.
Generating the NonStop SOAP 4 SDL File from the NonStop SOAP 3 SDR File The SoapAdminCL tool enables you to generate the NonStop SOAP 4 SDL file from the NonStop SOAP 3 SDR file to migrate services from NonStop SOAP 3 to NonStop SOAP 4. For information about the SDL file, see “NonStop SOAP 4 Service Description Language” (page 153). To generate the NonStop SOAP 4 SDL file from the NonStop SOAP 3 SDR file using the SoapAdminCL tool, complete the following steps: 1.
-casesensitive specifies the case in which the service name is generated. • when the –casesensitive option is used: If the SDR file defines a service name in mixed case, the SoapAdminCL –e
OSS>SoapAdminCL –dtd • Check the version of the SoapAdminCL tool using the following command: OSS>SoapAdminCL –v | -version • Invoke the command-line help of the SoapAdminCL tool using the following command: OSS>SoapAdminCL -h | -help | -? • Convert a transaction identifier from an external ASCII form to an internal form (\system-name(tm-flags).cpu.sequence).
• “Migrating to Contract-First Services” (page 208) • “WSDL2PWY Limitations” (page 210) Generating NonStop SOAP 4 Client Stubs The WSDL2PWY tool generates the NonStop SOAP 4 client stubs in the C programming language. The generated client stubs contain the interface code to be implemented when developing a client using NonStop SOAP 4 client APIs. To generate the NonStop SOAP 4 client stubs using the WSDL2PWY tool, complete the following steps: 1.
For example, use the following command to generate synchronous client stubs using the WSDL2PWY tool: OSS> WSDL2PWY –o "/home/nssoap/test/client" –s –uri "/home/nssoap/test/services/test_service/SoapPW_test.wsdl" where, /home/nssoap/test/client is the output location where the client stubs and the Makefile (Makefile_client) are generated. The client stubs are placed in the src directory in the output location.
4. Generate the Pathway service skeleton files using the WSDL2PWY command: OSS> WSDL2PWY [options] –ss –uri [wsdl_path] where, [options] includes the following: -o
Table 14 XML schema to C data type mapping (continued) Xml schema type Sample schema C data type mapping Duration
Table 14 XML schema to C data type mapping (continued) Xml schema type Sample schema C data type mapping float
1. For every operation, add the axis2_pway_xml_receiver message receiver in the services.xml file. For example:
WSDL2PWY Limitations The NonStop SOAP 4 WSDL2PWY tool is used to generate the Pathway service artifacts for contract-first development approach. This tool has some deviations from the WSDL specification and some limitations, which are discussed in this section. Table 26 lists the XML schema definitions, which deviate from WSDL specification and WSDL2PWY tool behavior for these XML schema definitions.
The WSDL2C Tool The WSDL2C tool is a standalone Java-based command-line tool that runs in the OSS environment on NonStop systems. This tool uses a WSDL file as an input to generate the client stubs and service skeleton files. The generated service skeleton files implement the basic interface code required while developing a service using NonStop SOAP 4 service APIs. NOTE: • The WSDL2PWY tool must be used when developing services implemented as Pathway applications.
where, /usr/tandem/nssoap/t0865h01 is the NonStop SOAP 4 installation directory location. 2. Add the directory containing the WSDL2C executable image to the OSS PATH variable. OSS> export PATH=
For example, use the following command to generate asynchronous client stubs using the WSDL2C tool: OSS> WSDL2C –o "/home/nssoap/test/client" –a –u –uri "/home/nssoap/test/services/test_service/SoapPW_test.wsdl" where, /home/nssoap/test/client is the output location. -uri /home/nssoap/test/services/test_service/SoapPW_test.wsdl specifies the WSDL Web address provided to the WSDL2C tool. 5.
[options] include the following: -o
The NonStop SOAP 4 Administration Utility The NonStop SOAP 4 Administration Utility is a graphical user interface (GUI) based utility that runs in the Microsoft Windows environment. This utility allows you to perform the following tasks: • Create new NonStop SOAP 4 SDL files. • Deploy new services on the NonStop SOAP 4 server using an existing SDL file.
4. Double-click the AdminTool.bat file (\T0904\SoapAdmin). The NonStop SOAP 4 Administration Utility screen appears. The NonStop SOAP 4 Administration Utility is now ready for use. NOTE: For information on using the NonStop SOAP 4 Administration Utility, see the NonStop SOAP 4 Administration Utility online help integrated with the NonStop SOAP 4 Administration Utility.
11 NonStop SOAP 4 Features This chapter provides information about the following features of NonStop SOAP 4: • “DDL Comments” (page 217) • “Hot-Deployment of the NonStop SOAP 4 Server” (page 229) • “Hot-Update for the Deployed Services” (page 229) • “Internationalization and Encoding” (page 230) • “Communicating with a Non-Pathway Process” (page 231) • “Validation Module” (page 233) • “SOAP_WSDL_NAME DDL Comment” (page 233) • “Support for Multiple DDL Definitions” (page 234) • “Check on SOA
?comments DEF FLD1. 02 FLD11. 03 FLD12. *@SOAP_ATTRIBUTE 04 FLD13 PIC X(20). END • The Operation tag in the SDL file must have the ProcessSoapDDLComments attribute set to yes. For example:
Example 5 A Sample DDL file with the @SOAP_OPTIONAL Tag ?comments DEF PATIENT. 02 PATIENT-DATA. 03 ID PIC 9(5). 03 AGE PIC 9(3). * @SOAP_OPTIONAL 03 HOSPITAL. 04 HOSP-NAME PIC X(30). 04 ADDRESS. 05 STREET PIC X(50). 05 CITY PIC X(25). 05 STATE PIC X(2). 05 ZIP PIC 9(5). 04 COUNTY. 05 CODE PIC 9(6). 05 Details. 06 COUNTY-NAME PIC X(15). 06 STATUS PIC X. 05 DESCRIPTION PIC X(100). END Example 6 shows the corresponding WSDL file generated using the SoapAdminCL tool.
Example 6 An XSD Schema for a Sample DDL file with the @SOAP_OPTIONAL Tag
Example 7 An XML Message-I for a Sample DDL file with the @SOAP_OPTIONAL Tag
Setting the SoapDDLAttribute in the SDL File The SDL file provides SoapDDLAttribute at the Service element level that accepts a value of yes or no. This enables you to flag all the DDL fields of a definition file without changing the DDL dictionary. • When set to yes, SoapDDLAttribute specifies that all the leaf fields of the request and response DDL definitions of the service must be represented as XML attributes.
The presence of the @SOAP_ATTRIBUTE comment tag at the leaf level denotes that the field must be translated to an XML attribute. If the @SOAP_ATTRIBUTE tag is present at the group level, it denotes that all the child leaf fields must be translated to XML attributes. The @SOAP_ELEMENT comment tag also works in the same manner as the @SOAP_ATTRIBUTE comment tag for the leaf and group levels, but translates the field(s) as XML elements, not as XML attributes.
Example 12 A Sample DDL File with the @SOAP_ATTRIBUTE and @SOAP_ELEMENT Tag ?comments DEF PATIENT. 02 PATIENT-DATA. * @SOAP_ATTRIBUTE 03 ID PIC 9(5). 03 AGE PIC 9(3). * @SOAP_ATTRIBUTE 03 NAME. 04 FIRST PIC X(20). 04 MIDDLE PIC X. 04 LAST PIC X(25). * @SOAP_ATTRIBUTE 03 HOSPITAL. 04 HOSP-NAME PIC X(30). * @SOAP_ELEMENT 04 ADDRESS. 05 STREET PIC X(50). 05 CITY PIC X(25). 05 STATE PIC X(2). 05 ZIP PIC 9(5). 04 COUNTY. * @SOAP_ATTRIBUTE 05 CODE PIC 9(6). * @SOAP_ELEMENT 05 COUNTY-NAME PIC X(15).
Table 17 SDL Values and DDL Comment Tags SOAPDDLAttribute Value ProcessSoapDDL Comments Value DDL Comment tag present? Effect Yes No Not Applicable All the DDL leaf fields, except OCCURS and OCCURS_DEP_ON leaf fields are XML attributes. Yes Yes No All the DDL leaf fields are XML attributes. Yes Yes Yes The DDL fields overridden with a comment tag are handled appropriately. All the other fields are XML attributes. No Yes Yes Only the fields containing the comment tags are processed.
Example 14 A Sample DDL file with the @SOAP_BASE64 Tag ?comments DEF PATIENT. 02 PATIENT-DATA. 03 ID PIC 9(5). 03 AGE PIC 9(3). 03 NAME. 04 FIRST PIC X(20). 04 MIDDLE PIC X. 04 LAST PIC X(25). * @SOAP_BASE64 03 BINARY-CONTENT type binary 32. END In the DDL file, the BINARY-CONTENT field is tagged as @SOAP_BASE64. This is indicated by the element type xsd:base64Binary in the XML schema present in the WSDL file and the XML schema file (shown in Example 15), created by the SoapAdminCL tool.
Example 17 shows that the occurrence of the fiction-details element in the SOAP message depends on the value of the fiction_count element. Example 17 A Sample DDL file with the @SOAP_OCCURS_DEP_ON Tag ?comments DEF books-in-lib. 02 fiction_count PIC 9(4) COMP. 02 libraries_fic PIC 9(4) COMP. 02 magazines_count PIC 9(4) COMP. 02 libraries_mag PIC 9(4) COMP. * @SOAP_OCCURS_DEP_ON fiction_count 02 fiction-details OCCURS 1000 TIMES. 03 call-num PIC 9(10).
Example 18 A Sample DDL file with the @SOAP_OCCURS_DEP_ON Tag ?comments DEFINITION REQ. 10 CH1 type character 2. 10 Bin32 type binary 32. 10 Complex1. 15 CH2 type character 4. 15 CH3 type character 1. 15 Bin2 type binary 32. 15 Complex2. 20 custnum PIC X(20) UPSHIFT. * @SOAP_OCCURS_DEP_ON Bin2 20 Bin3 type binary 32 OCCURS 5 times. END Example 19 shows the corresponding XML schema generated by the SoapAdminCL tool.
Example 20 The SOAP Message Body for a Sample DDL file with the @SOAP_OCCURS_DEP_ON Tag
Creating an SDL File to Communicate with a Non-Pathway Process The SDL file has a different hierarchy for a service, which is provided by a non-Pathway process. The new element
Validation Module The SOAP messages sent by the clients must be validated against the WSDL schema to ensure that correct data is received. The NonStop SOAP 4 validation module validates the received data. The validation module is a global module, and it is enabled by default. All the service requests to the NonStop SOAP 4 server are validated against the service WSDL schema by default. If the requests confirm to the schema, then the NonStop SOAP 4 server processes the requests.
For this conversion, NonStop SOAP 4 server uses DDLMapping.xml file to convert the request data to character buffer and response character buffer to XML. The server uses data definition structures stored in DDLMapping.xml file and their qualified names as a key for mapping. The considerations for using comment names in DDL Definition are: 1. 2.
NOTE: The same
12 Transaction Management As a value-added feature, NonStop SOAP 4 provides comprehensive support for Web services that implement transactions. A transaction, in this context, is defined as a series of logical operations against a database resulting from the receipt of one or more SOAP messages. All database changes must be done in their entirety, or all must be backed-out, to ensure that the database is in a consistent state once the transaction is complete.
NOTE: • For information on the TMFTransactionSupport, AbortTransactionOnFault, and TMFTimeout attributes, see “Configuring the Level of Transaction Support” (page 245) and “Transaction Timeouts” (page 246). • Previous versions of NonStop SOAP (SOAP 3 and earlier) defined the need to contain a multi-step transaction within a session, which was defined in a session header block in the SOAP message.
SOAP Server Transaction Management The NonStop SOAP 4 server can manage a simple transaction without a Transaction header block in the SOAP message. A client can invoke a service on the NonStop server and be certain that all the changes made to the database by that service are completed in their entirety or, should the transaction fail, the database restored to a prior state, using a single SOAP message.
Table 18 Attributes in the Transaction Header Block Attributes of the Header Element Values Description Command Begin, Continue, Commit, Abort Specifies the transaction command. Note that it is case-sensitive. TransactionID TMF TransactionID Contains the value set by TMF to identify a specific transaction. TimeOut Transaction timeout Specifies the transaction timeout in seconds.
Figure 17 Beginning a New Transaction TMF Request to begin a transaction Command = “Begin” SOAP Client Transaction ID Transaction ID NonStop SOAP 4 Server Invoke Service Response NonStop SOAP 4 Service When beginning a new TMF transaction, NonStop SOAP 4 performs the following activities: 1. The NonStop SOAP 4 server begins a new TMF transaction on behalf of a client request and optionally sets a value for the transaction timeout in its call to TMF.
4. If the invoked service returns a fault and the AbortTransactionOnFault attribute is set to yes, then the NonStop SOAP 4 server aborts the transaction and returns a SOAP fault to the client. The NonStop SOAP 4 server generates a temporary session identifier, because the current SessionID is no longer valid. The NonStop SOAP 4 server returns the session identifier in the session block header of the response message and sets this value for the SessionID attribute.
5. 6. the client. The NonStop SOAP 4 server generates a temporary session identifier because the current SessionID is no longer valid. The NonStop SOAP 4 server returns the session identifier in the session block header of the response message and sets this value for the SessionID attribute. If the invoked service returns a fault and the AbortTransactionOnFault attribute is set to yes, NonStop SOAP 4 aborts the transaction and returns a SOAP fault to the client.
When the SOAP server receives a request to commit an active TMF transaction, the following occurs: 1. The SOAP server resumes the TMF transaction specified in the TransactionID attribute of the transaction header block of the SOAP request. 2. The SOAP server invokes the operation (if specified in the body of the request) under the resumed TMF transaction. 3. When the service responds back to NonStop SOAP 4, a commit transaction request is sent to TMF and the SOAP response is sent back to the client.
Abort a Transaction To abort an active TMF transaction, the client must set the value of the TransactionID attribute (in the transaction header block of the NonStop SOAP request header element) to the value of the TransactionID attribute provided by a previous response from NonStop SOAP 4 associated with that transaction, and set the Command attribute to Abort. NOTE: HP recommends that the body of a request that aborts a transaction be empty.
Configuring the Level of Transaction Support You can configure the level of transaction management support for services deployed in NonStop SOAP 4 using the TMFTransactionSupport attribute. The TMFTransactionSupport attribute is configured at the operation level. The TMFTransactionSupport attribute can be set to one of the following values: • Required All operations in the SOAP request must be performed within a TMF transaction.
. 3. Save and close the services.xml configuration file. The TMFTransactionSupport attribute is an optional attribute. The default value of the TMFTransactionSupport attribute is Supports. Thus, if a client request includes a transaction header block in the SOAP request header, then NonStop SOAP 4 will process the Command attribute contained within it, even if the TMFTransactionSupport attribute is not set in the services.xml file.
NOTE: It is not possible to specify a timeout greater than the system-wide TMFAutoAbort value, which will supersede any attempt to set a higher value. Table 19 summarizes the timeout value that will be derived if any combination of attributes is defined by the SOAP client, SOAP server, and system-wide. Table 19 Transaction Timeout Timeout specified in the TimeOut attribute Timeout specified in TMFTimeout attribute No No Yes TMFAutoAbort timeout.
NOTE: • When developing a service, you can set the TMFTimeout attribute as an operation level attribute in the SDL file. • When deploying a service using the SoapAdminCL tool, the services.xml configuration file will have the TMFTimeout attribute set to a value specified in the SDL file. For more information about setting the TMFTimeoutattribute in the SDL file, see “NonStop SOAP 4 Service Description Language” (page 153).
. . 3. Save and close the services.xml configuration file. NOTE: • When developing a service, the AbortTransactionOnFault attribute can be set as an operation-level attribute in the SDL file. • When deploying a service using the SoapAdminCL tool, the services.xml configuration file will have the AbortTransactionOnFault attribute set to a value specified in the SDL file.
Begin a New Session To start a new session, the client must set the value of the SessionCommand attribute (in the session header block of the NonStop SOAP 4 request header element) to Begin. Figure 18 shows a schematic flow for beginning a new session. Figure 18 Beginning a New Session Session Command = “Begin” SOAP Client SessionID = “
Example 25 Begin a New Session Client Request Example 26 Begin a New Transaction within a Session Client Request Example 27 Begin a New Session and Transaction Combined Client Request Example 28 Continue a Transaction Client Request Example 29 Commit a Transaction within a Session Client Request Example 30 Abort a Transaction within a Session Client Request Example 31 End a Session Client Request
Example 32 Commit a Transaction and End a Session Client Request because once a transaction is committed or aborted, a session does not have any meaning, and does not hold any resources in NonStop SOAP, whereas in previous releases, its context was still maintained in the Cookie file and needed to be deleted once a session was ended. Subsessions Previous releases of NonStop SOAP (NonStop SOAP 3 and earlier) supported a feature called Subsessions, which was designed to allow the SOAP server to maintain a dialog with a context-sensitive server class.
13 Using the Contract-First Approach in NonStop SOAP 4 You can use the following approaches to develop client applications and services in NonStop SOAP 4: • Contract-first Approach - In this approach, the contract (WSDL file) is defined first, which states the type of service interface description that the service expects. The service code is generated based on this information.
NOTE: Ensure that the elements listed in Table 21 are not present in the WSDL file that is provided as an input to the WSDL2PWY tool. If present, your service may not function as expected. Table 21 Unsupported WSDL File Elements WSDL Components Elements Not Supported Description appInfo This element is application-specific and not supported on Pathway services.
Table 22 WSDL File Elements with Limited Support (continued) WSDL Components Elements with Limited Support Description normalizedString NonStop SOAP 4 does not normalize the string, sent in the Datatype for white spaces. Duration NonStop SOAP 4 handles Duration as xsd:string. NOTE: If you are not using a pre-defined WSDL file, you can create a new WSDL file from the DDL and SDL files by using the SoapAdminCL tool.
-uri specifies the location where the WSDL file is available. For example: OSS> WSDL2PWY -o "/home/usr/my_nssoap/services/reflector" -ss -uri "/home/usr/my_nssoap/services/reflector/SoapPW_reflector.wsdl" where, /home/usr/my_nssoap/services/reflector is the location where the service skeleton files will be generated. NOTE: Verify that the location of the Java executable object is included in the PATH environment variable.
iv. v. If an error occurs, the request is passed to the process_system_message() or file_error()function based on the error value. After a response is returned to the calling NonStop SOAP 4 server, the $RECEIVE file is closed. NOTE: The response buffer size is 32k. Use the -lps option while generating the skeleton files to pass large data. The data size limit is 2M. b. process_application_message() The process_application_message() function expects a character buffer as an argument (char *recv_buff).
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 recv_name_length = (short)strlen( recv_name ); /** * FILE_OPEN_ is called to obtain a unique file identifier (recv_num) * for $RECEIVE */ error = FILE_OPEN_( recv_name, recv_name_length, &recv_num, , /* Access */ , /* E
125 126 • } /* End of main() */ Line 10 The recv_num variable contains the file identifier for the $RECEIVE file and must be initialized to 0. Line 16 Defines the receiveinfo variable. The receiveinfo variable is passed as an argument to the FILE_GETRECEIVEINFO_ call. Line 21 The recv_name_length variable contains the length of the recv_name variable and must be initialized to 0.
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 • * count_transferred defined to be passed as argument * to operation_pway_
33 34 35 36 37 38 39 40 * Write the code implement business logic. The response buffer * needs to be written into variable response_buffer and response * size needs to be written into variable reply_count. * The memory needed for the response structure also needs to be * allocated. */ } Following is a list of functions based on the code sample: Line Number(s) Function Line 18 The fileError variable is used to check the returned error and must be initialized to 0.
Deploying a NonStop SOAP 4 Pathway Web Service A NonStop SOAP 4 Pathway Web service can be deployed using an external WSDL file (a WSDL file not generated by the SoapAdminCL tool). To deploy the Pathway Web service using an external WSDL file, complete the following steps: 1. Place the WSDL file in the
2. Access the reflector service, using the following Web address pattern: http://
14 WS–Security in NonStop SOAP 4 WS-Security provides a platform to secure your services beyond transport level protocols, such as HTTPS. HTTPS performs a secure message transfer from one end point to another. However, in the real world, the message is transferred over multiple domains and you must preserve the identity, integrity, and security of the message across multiple trusted domains or points. WS-Security provides an end-to-end solution for Web service security.
Figure 19 Alice 52ED879E Key Generation 70F71D92 Function Big Random Number Alice’s Public Key Alice’s Private Key These keys are used to encrypt the messages. For example, if Bob wants to send a message to Alice, he can encrypt a message using her public key. Alice can then decrypt this message using her private key. Only Alice can decrypt this message as she is the only one with the private key.
Figure 21 Alice Sign (Encrypt) I will pay $500 Alice’s Private Key DFCD3454 BBEA788A Bob I will pay $500 Verify (Decrypt) Alice’s Public Key Supported WS–Security Features The Rampart module, when engaged with NonStop SOAP 4, provides the following security features: 1. SOAP message encryption Any part of the SOAP message can be encrypted. NonStop SOAP 4 supports the following levels of message encryption: 2.
4. Timestamps Allows timestamps to be added to a message to enable the server to verify the message validity in terms of each SOAP message. 5. Username Tokens NonStop SOAP 4 can send and verify username tokens with Username and plaintext password or Username and digested password. 6. Protection Orders NonStop SOAP 4 supports encrypt before signing and sign before encrypting. 7. Extensible Modules NonStop SOAP 4 supports password provider module and authentication module. 8.
4. Providing Rampart specific configuration details Rampart module uses RampartConfig assertion to provide Rampart specific configuration details to Rampart Engine. You can use this configuration to specify the username, password type, path to the password provider library, and the path to certificates used for signing and encryption. Based on your security requirements, you can add the required RampartConfig assertions to the security policies.
Table 23 Rampart Specific Assertions Parameter Description Example User This denotes the username that must be
Publishing the Security Requirements The security requirements of the NonStop SOAP 4 service must be shared with the client program developer to build a secured SOAP message. The service developer provides the client program developer with a policy.xml file that contains the WS-SecurityPolicy assertions. You can extract the
1. Password provider • The service verifies if the incoming request message has the proper password set. For this, the Rampart module must retrieve the password associated with the username from the service and compare it with the one that is set in the request message. • The password can be stored in a database, LDAP or some other storage based on the service requirements. To make the password retrieval logic more flexible, Rampart provides the password callback provider.
Table 24 WS-Security Sample Programs Directory (continued) Directory Description Password Provider : This directory contains the source of sample password provider library ./extensible_modules/password_provider that can be used to retrieve the password for UserNameToken and for a private key. Authentication Provider : This directory contains the source of a sample authentication provider ./extensible_modules/authn_provider library.
Scenario 5: Combining TimeStamp, UsernameToken, Encryption, and Signature with Protection order Sign->Encrypt This scenario describes how TimeStamp, UsernameToken, Encryption, and Signature scenarios can be combined together. The following assertion can be used to encrypt the signature:
Recommendations While you design your security model for your services, you must study the potential threats to your model and what technologies or protocol can be used to mitigate each threat. The developers can use either the transport level security, such as HTTPS or WS-Security features or both to secure the services. Based on your company’s security requirements, it is recommended to review the security considerations section in the WS-Security specification. http://www.ws-i.
A NonStop SOAP 4 Error and Warning Messages If NonStop SOAP 4 encounters a situation that does not allow it to successfully serve a request, it logs an error message or a warning message in the soaperror.log file found in the /logs directory under the NonStop SOAP 4 deployment directory. The error and warning messages provides a brief description of the condition that prohibited NonStop SOAP 4 from serving the request.
Effect The request is not served. Recovery Correct the MEP used by the client for service invocation and try sending the request again. MEP mismatch. Cause There is a mismatch between the MEP used by the client and the one allowed by the service. Effect The request is not served. Recovery Correct the MEP used by the client for service invocation and try sending the request again.
Recovery Ensure that the invalid phase is removed from the NonStop SOAP 4 message flow. Edit the axi2.xml file to verify the correct phase order of the NonStop SOAP 4 deployment. Configuration file cannot be found. Cause NonStop SOAP 4 did not locate the axis2.xml configuration file. Effect The request is not served. Recovery Ensure that the valid axis2.xml file is present in the
Module validation failed. Cause The NonStop SOAP 4 server cannot engage the module. Effect The request is not served. Recovery Ensure that the shared libraries of all the modules are not corrupt and that they have proper permissions. Module XML file is not found in the given path. Cause The NonStop SOAP 4 server cannot engage the module. Effect The request is not served. Recovery Ensure that the module.
Recovery In case of non-Pathway services, ensure that the shared library of the service is proper and that the corresponding services.xml file is present with appropriate permissions. In case of Pathway services, ensure that the services.xml file and the WSDL file are present with appropriate permissions. Could not map the MEP URI to an Axis2/C MEP constant value. Cause An MEP other than the WSDL 2.0 specification is specified in the request. Effect The request is not served.
NonStop SOAP 4 Utility Errors NonStop SOAP 4 logs the following error messages when utility functions are incorrectly used. Could not open the file. Cause The NonStop SOAP 4 server cannot open the file. Effect The request is not served. Recovery Ensure that the reported file exists at the specified location with appropriate permissions. Failed in creating DLL. Cause The NonStop SOAP 4 server cannot engage a shared library. Effect The request is not served.
Cause The NonStop SOAP 4 server cannot locate the WSDL file for the service. Effect The request is not served. Recovery Check if the WSDL file is placed in the service directory and the correct reference is specified in the corresponding services.xml file. Error parsing WSDL file. Cause The NonStop SOAP 4 server cannot parse the WSDL file. Effect The request is not served. Recovery Check if the WSDL file is a well-formed XML file. Communication with service failed.
Effect The request is not served. Recovery Pass a value for the soapOccurs element that is less than or equal to the value of maxOccurs. Value of soapOccurs is less than value of minOccurs. Cause The client provided a value for the soapOccurs element, which is less than the minOccurs value specified in the WSDL file. Effect The request is not served. Recovery Pass a value for the soapOccurs element that is greater than or equal to the value of minOccurs.
Recovery None. The request XML is invalid. Cause The request message is not a well formed XML message. Effect The request is not served. Recovery Ensure that the request is a well formed XML message. Error occurred while processing the xsd:choice element. Cause An internal error occurred while processing the xsd:choice element. Effect The request is not served. Recovery None. Occurrence of an element in request was more than the soapOccurs comment specified in WSDL.
CGI Errors NonStop SOAP 4 logs the following error messages when there is a communication failure between the iTP WebServer and the CGI interface. CGI failed while writing response. Cause An internal error occurred between iTP WebServer and CGI communication. Effect The request is not served. Recovery Resend the request. CGI failed while writing response. Cause An internal error occurred between iTP WebServer and CGI communication. Effect The request is not served. Recovery Resend the request.
Recovery Send the request again with the Command attribute present in the transaction header block. Invalid transaction ID in transaction header. Cause The client request contains an invalid transaction identifier. Effect The request is not served. Recovery Send the request again with a valid transaction identifier. Invalid element in transaction header. Refer logs for detail.
Cause The client request tried to use transactions against a service that does not use transactions. Effect The request is not served. Recovery Access the service without using any transaction or session header block. Error occurred while ending transactions. Cause TMF failed to commit the transaction specified by the transaction identifier supplied by the client. Effect The request is not served. Recovery The error message will report the associated TMF error number.
Effect The command fails. Recovery Update the serverclass name to contain less than or equal to 15 characters, and run the SoapAdminCL command. Error>> Invalid DDL Dictionary Name:
Cause The syntax of the ResponseSelection element is incorrect. Effect The command fails. Recovery Correct the syntax of the ResponseSelection element to specify all or none of the attributes listed in the message, and run the SoapAdminCL command. Memory Allocation Errors The following log messages signify memory allocation errors. Parser - Error>>Internal error(SdlPway:parse) in the construction Cause Insufficient memory to run the SoapAdminCL command. Effect The command fails.
Cause This is due to the duplicate entry of the field name. Effect NonStop SOAP service deployment files will not be generated. Then, SoapAdminCL will exit. Recovery Remove the duplicate entry and use the same command again. SOAPADMIN ERROR >>Duplicate entry of DDL Definition
SOAPADMIN ERROR >> Error processing DDL definition
Cause The @SOAP_OCCURS_DEP_ON comment is applied to the field, which is not an OCCURS field. Effect The command fails. Recovery Check the validity of the DDL field and resolve the conflict. Regenerate the DDL dictionaries and run the SoapAdminCL command. SOAPADMIN ERROR >> The depends on field for the SOAP_OCCURS_DEP_ON comment tag was not found. Cause The depends on field is not defined in the DDL file mentioned in the @SOAP_OCCURS_DEP_ON comment. Effect The command fails.
Cause The same service name appears twice in the SDL file. Effect The command fails. Recovery Select a unique name for each service in the SDL file and run the SoapAdminCL command. SOAPADMIN ERROR >> HTML client file already exists... Cause The HTML client file exists at the mentioned location. Effect The command fails. Recovery Check whether the service is already deployed at the mentioned location.
WSDL2PWY and WSDL2C Error Messages The WSDL2PWY and WSDL2C utilities return the following errors when invalid options are specified. Error: The -o option was specified without a specifying the folder or with an improper folder name. Please note the tool usage: Cause The output folder is not specified or the folder name is incorrect. Effect The WSDL processing stops and the output files are not generated. Recovery Specify a valid folder name and run the tool. Error: The –uri option was not specified.
Effect The WSDL processing stops and the output files are not generated. Recovery Specify the –ss option with the –g option and run the tool. Error: Error Parsing Options Error Details: The option -sd was specified without specifying the option –ss Cause The –sd generate service descriptor option is specified without specifying the –ss option. Effect The WSDL processing stops and the output files are not generated. Recovery Specify the –ss option with the –sd option and run the tool.
Recovery None. OutputEncoding not set in message context. Cause The output encoding is not specified in the services.xml file. Effect The NonStop SOAP 4 server continues to serve the request. Recovery None. Body Stream not available for writing. Cause A client sends an empty HTTP request. Effect Internal server error is returned. Recovery The client needs to send a well-formed SOAP message. Byte buffer not available for writing. Cause A service sends an empty response.
Cause The axis2.xml file is corrupt. Effect None. Recovery Ensure that the axis2.xml file is well formed. Retrieving Axis2 configuration from Axis2 configuration context failed, Loading services failed. Cause The axis2.xml file is corrupt. Effect None. Recovery Ensure that the axis2.xml file is well formed. Retrieving Axis2 configuration from Axis2 configuration context failed. Initializing transports failed. Cause The axis2.xml file is corrupt. Effect None. Recovery Ensure that the axis2.
Skipping the validation for rpc type soap messages. Cause The SoapMessageType parameter is set to rpc in the services.xml file. Effect Validation of the request is skipped even when validation module is attached. Recovery Recommended to set the SoapMessageType parameter to document in the services.xml file.
B Install Files and Folders Verifying the Extracted Product Files The following files and directories are extracted in the
◦ ◦ • /transaction - includes the transaction module – libaxis2_mod_transaction.so – the transaction module – module.xml – the module configuration file for the transaction module /validation - includes the validation module – libValidationModule.so – the validation module – module.xml – the module configuration file for the validation module /sample_services ◦ /echo – Makefile - Makefile for the echo client application – echo.c - source file for the echo client echo.
◦ /modules – /empdb_MRUF – – – 310 – Makefile - Makefile for the empdb Message Receiver User Functions module – empdb_MRUF.c - source file for the empdb Message Receiver User Functions module – empdb_MRUF.h - header file for the empdb Message Receiver User Functions module /logging_MRUF – – /src /src – Makefile - Makefile for the logging Message Receiver User Functions module – logging_MRUF.c - source file for the logging Message Receiver User Functions module – logging_MRUF.
◦ /reflector – /conf – – ◦ pathConf - Pathway configuration file for the reflector service /src – reflector.c - source file for the reflector service – reflectorddl - DDL file for the reflector service – reflectorsdl.xml - SDL file for the reflector service sec_echo – README - explains how to set up sample client repository and how to run the scenario samples provided. – /client – sec_echo.txe - sample client application used to access the sec_echo service.
◦ • – echo.h - header file for the sec_echo service. – echo_skeleton.c - source file for the sec_echo service. setup.sh - A script to set up sample WS-Security client repository used to run the scenarios. /tools - includes the tools distributed with NonStop SOAP 4 ◦ SoapAdminCL.txe - tool to generate the HTML clients, the WSDL file, SOAP request and response XML files, XML schema files, and the services.xml file using the NonStop SOAP 4 Service Definition Language (SDL) file.
• ◦ /transaction - is a soft link to the transaction module directory in
C SoapAdminCL DDL datatype to XML datatype conversion SoapAdminCL converts the DDL datatypes to the corresponding XML schema type to generate the WSDL. This maps the data structure defined in DDL to the XML schema in the WSDL.
Table 25 SoapAdminCL conversion table for DDL datatype to XML datatype Conversion: (continued) DDL Datatype Schema datatype TYPE LOGICAL 4 xsd:int ENUM xsd:short totalDigits = 2 NOTE: The following DDL elements are not supported by the SoapAdminCL tool: • BINARY 64 UNSIGNED for COBOL.
D NonStop SOAP 4 APIs This appendix lists the following NonStop SOAP 4 APIs: • “AXIOM APIs” (page 316) • “Client API Module” (page 343) • “Context Hierarchy” (page 365) • “Service Skeleton API” (page 373) • “Utilities” (page 374) AXIOM APIs Attributes The axiom_attribute_create()Function The axiom_attribute_create()function creates an AXIOM attribute structure.
env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: The axiom_attribute_get_qname() Function Synopsis: AXIS2_EXTERN axutil_qname_t* axiom_attribute_get_qname ( struct axiom_attribute * om_attribute, const axutil_env_t * env ) Description: This function creates and returns a qname structure for this attribute.
Parameters: om_attribute is a pointer to attribute structure. env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: This function returns the localname and returns NULL on error. The axiom_attribute_get_value()Function Synopsis: AXIS2_EXTERN axis2_char_t* axiom_attribute_get_value ( struct axiom_attribute * om_attribute, const axutil_env_t * env ) Description: This function returns value of this attribute.
Parameters: om_attribute pointer to om_attribute structure env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. localname is the localname that should be set for this attribute.
om_namespace is a pointer to om_namespace structure that should be set for this attribute. Return Values: This function returns: • AXIS2_SUCCESS on success • AXIS2_FAILURE on failure Comment The axiom_comment_create() Function Synopsis: AXIS2_EXTERN axiom_comment_t* axiom_comment_create ( const axutil_env_t * env, axiom_node_t * parent, const axis2_char_t * value, axiom_node_t ** node ) Description: This function creates a comment structure.
The axiom_comment_get_value() Function Synopsis: AXIS2_EXTERN axis2_char_t* axiom_comment_get_value ( struct axiom_comment * om_comment, const axutil_env_t * env ) Description: This function gets the comments data Parameters: om_comment pointer to axis2_commnet_t structure to be freed env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: This function returns the comment text.
Parameters: env is a pointer to the environment structure. The env parameter must not be NULL. root pointer to document's root node. Optional, can be NULL. builder pointer to axiom_stax_builder. Return Values: This function returns a pointer to the newly created document. axiom_document_free Synopsis: AXIS2_EXTERN void axiom_document_free ( struct axiom_document * document, const axutil_env_t * env ) Description: This function frees the document structure.
Description: This function sets the root element of the document. If a root node already exists, it is freed before setting to root element. Parameters: document document structure to return the root of. env is a pointer to the environment structure. The env parameter must not be NULL. Return Values: This function returns the status code AXIS2_SUCCESS on success , else returns AXIS2_FAILURE on error.
freed. If the value of the namespace has already been declared using another namespace structure then the namespace structure ns will be freed. node This is an out parameter. cannot be NULL. Returns the node corresponding to the comment created.
Return Values: This function returns the status of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE. axiom_element_get_attribute Synopsis: AXIS2_EXTERN axiom_attribute_t* axiom_element_get_attribute ( axiom_element_t * om_element, const axutil_env_t * env, axutil_qname_t * qname ) Description: This function gets (finds) the attribute with the given qname. Parameters: element element whose attribute is to be found. env is a pointer to the environment struct. The env parameter must not be NULL.
env is a pointer to the environment struct. The env parameter must not be NULL. qname qname of the attribute to be found. should not be NULL. Return Values: This function returns the status of the operation. It returns AXIS2_SUCCESS on success , else returns AXIS2_FAILURE on error. axiom_element_get_localname Synopsis: AXIS2_EXTERN axis2_char_t* axiom_element_get_localname ( axiom_element_t * om_element, const axutil_env_t * env ) Description: This function returns the local name of this element.
Parameters: om_element pointer to om_element. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This pointer returns a pointer to axiom_namespace_t structure NULL if there is no namespace associated with the element, NULL on error with error code set to environment's error.
Description: This function returns a list of children iterator returned iterator is freed when om_element structure is freed iterators reset function must be called by user Parameters: om_element pointer to om_element. env is a pointer to the environment struct. The env parameter must not be NULL. element_node pointer to this element node.
Return Values: This function returns AXIS2_SUCCESS if the attribute was found and removed, else returns AXIS2_FAILURE. axiom_element_set_text Synopsis: AXIS2_EXTERN axis2_status_t axiom_element_set_text ( axiom_element_t * om_element, const axutil_env_t * env, const axis2_char_t * text, axiom_node_t * element_node ) Description: This function sets the text of the given element. CAUTION: This method will wipe out all the text elements (and hence any mixed content) before setting the text.
axiom_element_to_string Synopsis: AXIS2_EXTERN axis2_char_t* axiom_element_to_string ( axiom_element_t * om_element, const axutil_env_t * env, axiom_node_t * element_node ) Description: This function returns the serilized text of this element and its children Parameters: om_element pointer to om_element. env is a pointer to the environment struct. The env parameter must not be NULL. element_node the container node this element is contained on.
env is a pointer to the environment struct. The env parameter must not be NULL. om_node pointer to this element node. Return Values: axiom_element_get_attribute_value_by_name Synopsis: AXIS2_EXTERN axis2_char_t* axiom_element_get_attribute_value_by_name ( axiom_element_t * om_ele, const axutil_env_t * env, axis2_char_t * attr_name ) Description: This function returns the attribute value as a string for the given element. Parameters: om_element pointer to om_element.
Parameters: om_element pointer to om_element env is a pointer to the environment struct. The env parameter must not be NULL. localname the local name of the element.
Description: This function compares two namepsaces. Parameters: om_namespace first namespace to be compared env is a pointer to the environment struct. The env parameter must not be NULL. om_namespace1 second namespace to be compared Return Values: This funtion returns AXIS2_TRUE if the two namespaces are equal, AXIS2_FALSE otherwise.
axiom_namespace_get_prefix Synopsis: AXIS2_EXTERN axis2_char_t* axiom_namespace_get_prefix ( struct axiom_namespace * om_namespace, const axutil_env_t * env ) Description: Parameters: om_namespace pointer to om_namespace structure env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns the prefix or NULL on error.
const axutil_env_t * env, axutil_string_t * uri ) Description: This function sets the uri string. Parameters: om_namespace pointer to the AXIOM namespace structure env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
Description: This function creates a node struct. Parameters: env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to newly created node struct. NULL on error. axiom_node_free_tree Synopsis: AXIS2_EXTERN void axiom_node_free_tree ( axiom_node_t * om_node, const axutil_env_t * env ) Description: This function frees an AXIOM node and all of its children.
const axutil_env_t * env, axiom_node_t * node_to_insert ) Description: This function inserts a sibling node after the given node. Parameters: om_node parent node. cannot be NULL. env is a pointer to the environment struct. The env parameter must not be NULL. node_to_insert the node to be inserted. Cannot be NULL. Return Values: This function returns the status of the op. It returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
om_output AXIOM output handler to be used in serializing. Return Values: This function returns the status of the operation. This function returns AXIS2_SUCCESS on success, else AXIS2_FAILURE. axiom_node_get_parent Synopsis: AXIS2_EXTERN axiom_node_t* axiom_node_get_parent ( axiom_node_t * om_node, const axutil_env_t * env ) Description: This function gets parent of om_node node. Parameters: env is a pointer to the environment struct. The env parameter must not be NULL.
Return Values: This function returns a pointer to first child AXIOM element, NULL is returned on error with error code set in environments error. axiom_node_get_last_child Synopsis: AXIS2_EXTERN axiom_node_t* axiom_node_get_last_child ( axiom_node_t * om_node, const axutil_env_t * env ) Description: This function gets the last child of the node. Parameters: om_node node env is a pointer to the environment struct. The env parameter must not be NULL.
axiom_node_get_node_type Synopsis: AXIS2_EXTERN axiom_types_t axiom_node_get_node_type ( axiom_node_t * om_node, const axutil_env_t * env ) Description: This function gets the node type of this element Node type can be one of AXIOM_ELEMENT, AXIOM_COMMENT, AXIOM_TEXT, AXIOM_DOCTYPE, AXIOM_PROCESSING_INSTRUCTION. Parameters: om_node node of which node type is required env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns the node type.
axiom_node_to_string Synopsis: AXIS2_EXTERN axis2_char_t* axiom_node_to_string ( axiom_node_t * om_node, const axutil_env_t * env ) Description: This function Parameters: om_node pointer to the AXIOM node structure env is a pointer to the environment struct. The env parameter must not be NULL.
Parameters: env is a pointer to the environment struct. The env parameter must not be NULL. om_text pointer to AXIOM text structure to be freed. Return Values: This function returns the status of the op. It returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE on error.
axiom_text_get_value Synopsis: AXIS2_EXTERN const axis2_char_t* axiom_text_get_value ( struct axiom_text * om_text, const axutil_env_t * env ) Description: This function gets text value. Parameters: om_text om_text structure env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns the text value , NULL is returned if there is no text value.
env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to service context struct. The service client owns the returned pointer. axis2_svc_client_set_options Synopsis: AXIS2_EXTERN axis2_status_t axis2_svc_client_set_options ( axis2_svc_client_t * svc_client, const axutil_env_t * env, const axis2_options_t * options ) Description: This function sets the options to be used by service client.
Description: This function engages the named module. The engaged modules extend the message processing when consuming services. Modules help to apply QoS norms in messaging. After a module is engaged to a service client, the axis2_engine invokes the module for all the interactions between the client and the service. Parameters: svc_client pointer to service client struct. env is a pointer to the environment struct. The env parameter must not be NULL. module_name name of the module to be engaged.
header AXIOM node representing the SOAP header in XML. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE. axis2_svc_client_remove_all_headers Synopsis: AXIS2_EXTERN axis2_status_t axis2_svc_client_remove_all_headers ( axis2_svc_client_t * svc_client, const axutil_env_t * env ) Description: This function removes all the headers added to service client. Parameters: svc_client pointer to service client struct. env is a pointer to the environment struct.
Description: This function sends a message and forget about it. This method is used to interact with a service operation whose MEP is In-Only. That is, there is no opportunity to get an error from the service via this method; one may still get client-side errors, such as host unknown etc. Parameters: svc_client pointer to service client struct. env is a pointer to the environment struct. The env parameter must not be NULL. payload pointer to AXIOM node representing the XML payload to be sent.
env pointer to the environment structure op_qname operation qname. NULL is equivalent to an operation name of "__OPERATION_OUT_IN__". payload pointer to OM node representing the XML payload to be sent. The caller has control over the payload until the service client frees it. Return Values: This function returns a pointer to OM node representing the XML response. The caller owns the returned node.
axis2_svc_client_free Synopsis: AXIS2_EXTERN void axis2_svc_client_free ( axis2_svc_client_t * const axutil_env_t * svc_client, env ) Description: This function frees the service client. Parameters: svc_client pointer to service client struct. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
axis2_options_get_fault_to Synopsis: AXIS2_EXTERN axis2_endpoint_ref_t* axis2_options_get_fault_to ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets WSA fault to address. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to endpoint reference structure representing fault to address if set, else returns NULL.
axis2_options_get_transport_in Synopsis: AXIS2_EXTERN axis2_transport_in_desc_t* axis2_options_get_transport_in ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets transport in. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to transport in structure if set, else NULL.
axis2_options_get_properties Synopsis: AXIS2_EXTERN axutil_hash_t* axis2_options_get_properties ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets the properties hash map. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to the properties hash map if set, else returns NULL.
axis2_options_get_reply_t Synopsis: AXIS2_EXTERN axis2_endpoint_ref_t* axis2_options_get_reply_to ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets the WSA reply_to address. Parameters: options pointer to options structure env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns a pointer to the endpoint reference structure representing reply to address if set, else returns NULL.
xis2_options_get_soap_version_uri Synopsis: AXIS2_EXTERN const axis2_char_t* axis2_options_get_soap_version_uri ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets the SOAP version URI. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns the string representing SOAP version URI.
axis2_options_set_parent Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_parent ( axis2_options_t * options, const axutil_env_t * env, const axis2_options_t * parent ) Description: This function sets the parent options. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. parent pointer to parent options struct. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
fault_to pointer to endpoint reference structure representing fault_to address. options takes over the ownership of the struct. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE. axis2_options_set_from Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_from ( axis2_options_t * options, const axutil_env_t * env, axis2_endpoint_ref_t * from ) Description: This function sets from address. Parameters: options pointer to options struct.
Description: This function sets transport receiver. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. receiver pointer to transport receiver struct options takes over the ownership of the struct. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
axis2_options_set_message_id Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_message_id ( axis2_options_t * options, const axutil_env_t * env, const axis2_char_t * message_id ) Description: This function sets message ID. Parameters: options pointer to options structure env is a pointer to the environment struct. The env parameter must not be NULL. message_id pointer to message_id structure Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
env is a pointer to the environment struct. The env parameter must not be NULL. property_key property key string. property pointer to property to be set. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE. axis2_options_set_reply_to Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_reply_to ( axis2_options_t * options, const axutil_env_t * env, axis2_endpoint_ref_t * reply_to ) Description: This function sets reply to address.
axis2_options_set_sender_transport Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_sender_transport ( axis2_options_t * options, const axutil_env_t * env, const AXIS2_TRANSPORT_ENUMS sender_transport, axis2_conf_t * conf ) Description: This function sets the sender transport. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. sender_transport name of the sender transport to be set.
Parameters: options pointer to options structure env is a pointer to the environment struct. The env parameter must not be NULL. timeout_in_milli_seconds timeout in milli seconds. The value can range from 0 to 2,147,483,647 milli seconds. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
axis2_options_set_manage_session Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_manage_session ( axis2_options_t * options, const axutil_env_t * env, const axis2_bool_t manage_session ) Description: This function sets manage session bool value. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. manage_session manage session bool value.
Return Values: This function returns pointer to message information headers structure if set, else returns NULL. axis2_options_get_soap_version Synopsis: AXIS2_EXTERN int axis2_options_get_soap_version ( const axis2_options_t * options, const axutil_env_t * env ) Description: This function gets SOAP version. Parameters: options pointer to options structure env is a pointer to the environment struct. The env parameter must not be NULL. Return Values: This function returns AXIOM_SOAP11 if SOAP version 1.
Return Values: This function returns SOAP Action string if set, else returns NULL. axis2_options_set_soap_action Synopsis: AXIS2_EXTERN axis2_status_t axis2_options_set_soap_action ( axis2_options_t * options, const axutil_env_t * env, axutil_string_t * soap_action ) Description: This function sets the SOAP action. Parameters: options pointer to options struct. env is a pointer to the environment struct. The env parameter must not be NULL. action pointer to SOAP action string.
http_header_list array list containing HTTP Headers. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE. axis2_options_create Synopsis: AXIS2_EXTERN axis2_options_t* axis2_options_create ( const axutil_env_t * env ) Description: This function creates the options struct. Parameters: env is a pointer to the environment struct. The env parameter must not be NULL.
Return Values: This function returns a pointer to operation context which is the parent. The axis2_msg_ctx_set_parent()Function Synopsis: AXIS2_EXTERN axis2_status_t axis2_msg_ctx_set_parent ( axis2_msg_ctx_t * msg_ctx, const axutil_env_t * env, struct axis2_op_ctx * parent ) Description: This function sets the parent. Parent of a message context is of type operation context. Parameters: msg_ctx is the message context env is a pointer to an environment structure. It cannot have a NULL value.
env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns a pointer to the SOAP envelope stored within message context. The axis2_msg_ctx_get_response_soap_envelope()Function Synopsis: AXIS2_EXTERN struct axiom_soap_envelope* axis2_msg_ctx_get_response_soap_envelope msg_ctx, const axutil_env_t * env ) ( const axis2_msg_ctx_t * Description: This function gets the SOAP envelope of the response.
msg_id Return Values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure. The axis2_msg_ctx_get_msg_id()Function Synopsis: AXIS2_EXTERN const axis2_char_t* axis2_msg_ctx_get_msg_id ( const axis2_msg_ctx_t * msg_ctx, const axutil_env_t * env ) Description: This function gets the message ID. Parameters: msg_ctx is the message context env is a pointer to an environment structure. It cannot have a NULL value.
env is a pointer to an environment structure. It cannot have a NULL value. soap_envelope is a pointer to the SOAP envelope. The message context assumes ownership of SOAP envelope. Return Values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure.
The axis2_msg_ctx_set_message_id()Function Synopsis: AXIS2_EXTERN axis2_status_t axis2_msg_ctx_set_message_id ( axis2_msg_ctx_t * msg_ctx, const axutil_env_t * env, const axis2_char_t * message_id ) Description: This function sets the message ID. Parameters: msg_ctx is the message context. env is a pointer to an environment structure. It cannot have a NULL value. message_id Return Values: • AXIS2_SUCCESS on success. • AXIS2_FAILURE on failure.
env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns a pointer to message information headers structure with WS-Addressing information. It returns a reference, not a cloned copy. The axis2_msg_ctx_is_keep_alive()Function Synopsis: AXIS2_EXTERN axis2_bool_t axis2_msg_ctx_is_keep_alive ( const axis2_msg_ctx_t * msg_ctx, const axutil_env_t * env ) Description: This function gets the boolean value indicating the keep alive status.
Description: This function gets operation context related to the operation that this message context is related to. Parameters: msg_ctx is the message context. env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns a pointer to operation context structure.
The axis2_msg_ctx_get_conf_ctx()Function Synopsis: AXIS2_EXTERN struct axis2_conf_ctx* axis2_msg_ctx_get_conf_ctx ( const axis2_msg_ctx_t * msg_ctx, const axutil_env_t * env ) Description: This function gets the configuration context. Parameters: msg_ctx is the message context. env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns pointer to configuration context.
AXIS2_SVC_SKELETON_FREE Synopsis: #define AXIS2_SVC_SKELETON_FREE ( svc_skeleton, env ) ((svc_skeleton)->ops->free (svc_skeleton, env)) Description: Frees the svc skeleton. AXIS2_SVC_SKELETON_INVOKE Synopsis: #define AXIS2_SVC_SKELETON_INVOKE ( svc_skeleton, env, node, msg_ctx ) ((svc_skeleton)->ops->invoke (svc_skeleton, env, node, msg_ctx)) Description: Invokes axis2 service skeleton.
The axutil_log_impl_log_error()Function Synopsis: AXIS2_EXTERN void axutil_log_impl_log_error (axutil_log_t *log, const axis2_char_t *filename, const int linenumber, const axis2_char_t *format,...) Description: This function logs the error messages in the specified log file. Parameters: log is a pointer to the log structure. filename is the name of the file in which logs are recorded. linenumber specifies the line number where the message is generated.
format is the string format of the message The axutil_log_impl_log_user()Function Synopsis: AXIS2_EXTERN void axutil_log_impl_log_user (axutil_log_t *log, const axis2_char_t *filename, const int linenumber, const axis2_char_t *format,...) Description: This function logs user-level debug messages in the specified log file. Parameters: log is a pointer to the log structure. filename is the name of the file in which logs are recorded. linenumber specifies the line number where the message is generated.
linenumber specifies the line number where the message is generated. format is the string format of the message The axutil_log_free()Function Synopsis: AXIS2_EXTERN void axutil_log_free (axutil_allocator_t *allocator, struct axutil_log *log) Description: This function releases the log files. Parameters: allocator is the allocator to be used. It is a mandatory parameter and cannot have a Null value. log is a pointer to the log structure that is freed. Return Values: Void.
Return Values: This function returns a pointer to the newly created log structure. Utilities For Error Reporting The following functions set the error code and error message during run time. The axutil_error_free() Function Synopsis: AXIS2_EXTERN void axutil_error_free ( struct axutil_error * error) Description: This function de-allocates an error structure instance. Parameters: error is a pointer to an error structure instance to be freed. Return Values: Void.
The axutil_error_set_error_number() Function Synopsis: AXIS2_EXTERN axis2_status_t axutil_error_set_error_number ( struct axutil_error * error, axutil_error_codes_t error_number ) Description: This function sets the error number to the given value. Parameters: error is a pointer to an error structure instance. error_number is the error number to be set. Return Values: This function returns AXIS2_SUCCESS on success, else returns AXIS2_FAILURE.
The axutil_strdup()Function Synopsis: AXIS2_EXTERN void * axutil_strdup (const axutil_env_t *env, const void *ptr) Description: This function duplicates the string passed to it. Parameters: env is a pointer to an environment structure. It cannot have a NULL value. ptr is a pointer to the string that is duplicated. Return Values: This function returns a pointer to the newly created string.
env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. Return Values: This function returns the new string. The axutil_strcmp()Function Synopsis: AXIS2_EXTERN int axutil_strcmp (const axis2_char_t *s1, const axis2_char_t *s2) Description: This function compares the strings passed to it. Parameters: s1 is the first string passed to the function. s2 is the second string passed to the function.
Parameters: s is the string passed. Return Values: This function returns the length of the string. The axutil_strcasecmp() Function Synopsis: AXIS2_EXTERN int axutil_strcasecmp (const axis2_char_t *s1, const axis2_char_t *s2) Description: This function compares two strings. Parameters: s1 is the first string to be compared. s2 is the second string to be compared. Return Values: • The function returns zero if the two strings are identical.
Parameters: env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. s1 is the first string. s2 is the second string. Return Values: This function returns the new string. The axutil_strcat() Function Synopsis: AXIS2_EXTERN axis2_char_t* axutil_strcat ( const axutil_env_t * ... ) env, Description: This function concatenates multiple strings. Parameters: env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. ...
Description: This function finds the first occurrence of the substring needle in the string haystack. It ignores the case of both arguments. Parameters: haystack is the string in which the given string is to be found. needle is the string to be found in haystack. Return Values: This function returns pointer to the beginning of the substring, or NULL if the substring is not found.
The axutil_strltrim()Function Synopsis: AXIS2_EXTERN axis2_char_t * axutil_strltrim (const axutil_env_t *env, const axis2_char_t *s, const axis2_char_t *trim) Description: This function trims the sequence or pattern specified in trim from the left of the string. Parameters: env is an input parameter and is a pointer to the environment structure. It cannot have a NULL value. s is the string which is trimmed. trim specifies the sequence or pattern to be trimmed.
s is the string which is trimmed. trim specifies the sequence or pattern to be trimmed. Return Values: This function returns the new string. The axutil_string_replace()Function Synopsis: AXIS2_EXTERN axis2_char_t* axutil_string_replace ( axis2_char_t * str, axis2_char_t old_char, axis2_char_t new_char ) Description: This function replaces the given axis2_character with a new one.
Parameters: str is the source string. c is the ending index. Return Values: This function returns the substring. The axutil_string_tolower() Function Synopsis: AXIS2_EXTERN axis2_char_t* axutil_string_tolower ( axis2_char_t * str ) Description: This function sets a string to lowercase. Parameters: str is the string to be converted to lowercase. Return Values: This function returns the string with lowercase.
Return Values: This function returns the newly created array list. The axutil_array_list_size()Function Synopsis: AXIS2_EXTERN int axutil_array_list_size ( struct axutil_array_list * array_list, const axutil_env_t * env ) Description: This function returns the number of elements in this list. Parameters: array_list is a pointer to the array list. env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns the list size.
e is the element whose inclusion in the list is being tested. Return Values: This function returns true if the list contains e. The axutil_array_list_add() Function Synopsis: AXIS2_EXTERN axis2_status_t axutil_array_list_add ( struct axutil_array_list * const axutil_env_t * env, const void * e ) array_list, Description: This function appends the supplied element to the end of this list. The element, e, can be a pointer of any type or NULL. Parameters: array_list is a pointer to the array list.
The axutil_array_list_remove() Function Synopsis: AXIS2_EXTERN void* axutil_array_list_remove ( struct axutil_array_list * const axutil_env_t * env, int index ) array_list, Description: This function removes the element at the user-supplied index. Parameters: array_list is a pointer to the array list. env is a pointer to an environment structure. It cannot have a NULL value. index is the index at which the element is being added. Return Values: This function returns the the removed void* pointer.
Parameters: hi The iteration state. Return Values: This function returns a pointer to the updated iteration state. It returns NULL if there are no more entries. The axutil_hash_count()Function Synopsis: AXIS2_EXTERN unsigned int axutil_hash_count ( axutil_hash_t * ht ) Description: This function gets the number of key/value pairs in the hash table. Parameters: ht is the hash table. Return Values: This function returns the number of key/value pairs in the hash table.
The axutil_hash_make()Function Synopsis: AXIS2_EXTERN axutil_hash_t* axutil_hash_make ( const axutil_env_t * env ) Description: This function creates a hash table. Parameters: env is a pointer to an environment structure. It cannot have a NULL value. Return Values: This function returns the newly created hash table.
Return Values: If the value is NULL the hash entry is deleted. qname The axutil_qname_create()Function Synopsis: AXIS2_EXTERN axutil_qname_t* axutil_qname_create ( const axutil_env_t const axis2_char_t const axis2_char_t const axis2_char_t * * * * env, localpart, namespace_uri, prefix ) Description: This function creates a qname structure returns a pointer to a qname structure mandatory mandatory optional The prefix. Must not be null.
Parameters: Return Values: This function returns true if qname1 equals qname2, false otherwise. The axutil_qname_clone()Function Synopsis: AXIS2_EXTERN struct axutil_qname* axutil_qname_clone ( struct axutil_qname * qname, const axutil_env_t * env ) Description: This function clones a given qname.
Description: Parameters: Return Values: The axutil_qname_to_string()Function Synopsis: AXIS2_EXTERN axis2_char_t* axutil_qname_to_string ( struct axutil_qname * qname, const axutil_env_t * env ) Description: Parameters: Return Values: This function returns a unique string created by concatenating namespace uri and localpart. The string is of the form localpart|url. When the qname free function is called, the returned char* is freed.
Parameters: Return Values: Thjis function returns the object.
Parameters: value Return Values: The axutil_param_free()Function Synopsis: AXIS2_EXTERN void axutil_param_free (struct axutil_param *param, const axutil_env_t *env) Description: Parameters: Return Values: The axutil_param_set_attributes()Function Synopsis: AXIS2_EXTERN axis2_status_t axutil_param_set_attributes (struct axutil_param *param, const axutil_env_t *env, axutil_hash_t *attrs) Description: Parameters: Return Values: Synopsis: AXIS2_EXTERN axutil_hash_t * axutil_param_get_attributes (struct a
E Transaction Management Model in NonStop SOAP 3 and NonStop SOAP 4 The transaction management model followed by NonStop SOAP 4 is different from the transaction management model of NonStop SOAP 3. “Transaction Management Models in NonStop SOAP 3 and NonStop SOAP 4” (page 398) highlights the differences between NonStop SOAP 3 Transaction Management Model and the NonStop SOAP 4 Transaction Management model.
Glossary A administrator For a NonStop system, the person responsible for the installation and configuration of a software subsystem on a NonStop node. Contrast with operator. ANSI The American National Standards Institute. API See application program interface. application program interface A set of services (such as programming language functions or procedures) that are called by an application program to communicate with other software components.
D Data Definition Language (DDL). The set of data definition statements within the Structured Query Language (SQL). An HP product for defining data objects in Enscribe files on NonStop™ systems and translating object definitions into source code. data type A categorization of values, operations, and arguments that usually cover both behavior and representation.
File Utility Program (FUP). An HP product on NonStop™ systems that allows users to create, copy, purge, and otherwise manipulate disk files interactively. Flows A Flow is a sequence of activities where messages flow in and out of NonStop SOAP 4. FTP See File Transfer Protocol (FTP). fully qualified file name. The complete name of a file in the Guardian environment. For a permanent disk file, this consists of a node name (system name), volume name, subvolume name, and file identifier (file ID).
Message Receiver User Functions (MRUFs) These are a set functions that can be used to customize the Pathway message receiver process flow. N NonStop Process A process running on a NonStop server. NonStop SOAP configuration file An XML document that defines the environment variables used by a SOAP server at runtime. O Open System Services (OSS) An open system environment available for interactive or programmatic use with the NonStop™ operating system.
Phase A Phase is a stage of processing or a time interval in the message process. A collection of phases forms a Flow. process A running entity that is managed by the operating system, as opposed to a program, which is a collection of code and data. When a program is taken from a file on a disk and run in a processor, the running entity is called a process. R request message buffer A character buffer created by the NonStop SOAP 4 server to be sent to the Pathway application or NonStop process.
T TMF See Transaction Management Facility subsystem. TMF transaction See Transaction Management Facility subsystem and transaction. transaction An operation or a series of operations that retrieves and updates information to reflect an exchange of goods or services. In the process of retrieving and updating information, a transaction transforms a database from one consistent state to another.
Index creating log file structure, 115 logging levels, 115 releasing log structure, 116 defining log levels, 178 log levels, 178 Service APIs, 95 creating log file structure, 95 A Abort AbortTransactionOnFault attribute, 162 configuring transactions to Abort on fault, 248 Session, 255 timeout, 246 Transaction, 244 Attaching module at global level, 181 MRUF at global level, 181 C Client APIs Basic client APIs, 105 to generate Request Node and consume Response Node, 106 to implement the Client Interface, 10
Creating SDL for service, 98 elements, 153 service types, 154 Service APIs Basic service APIs, 85 developing services, 95 logging, 95 to extract input parameters and return response, 89 to implement the Service Interface, 85 to implement the Service Skeleton Structure interface, 87 Session Abort Transaction in Session, 255 Begin, 250 Begin Transaction in Session, 251 Commit Transaction in Session, 254 Continue Transaction in Session, 253 End, 256 subsessions, 259 timeout, 258 Session Management, 249 T Time