Server API Functions - version 1.3 only

The following table lists the APIs to create a Web Services server in BDL.

Note: These functions are valid for backwards compatibility, but they are not the preferred way to handle Genero Web Services. See the GWS COM Library classes and methods.

Function	Description
fgl_ws_server_setNamespace()	Defines the namespace of the service on the Web.
fgl_ws_server_start()	Creates and starts the Web Service server.
fgl_ws_server_publishFunction()	Publishes the BDL function as a Web Function.
fgl_ws_server_generateWSDL()	Generates the WSDL file.
fgl_ws_server_process()	Waits for and processes incoming SOAP requests.
fgl_ws_server_setFault()	Sets the SOAP fault string for a Web Function.
fgl_ws_server_getFault()	Retrieves the fault string that was set for a Web Function, for testing purposes.

fgl_ws_server_setNamespace() (version 1.3)

Purpose:

This function defines the namespace of the service on the Web and must be called first, before all other functions of the API.

Syntax:

FUNCTION fgl_ws_server_setNamespace(namespace VARCHAR)

Parameters:

namespace is the name of the namespace.

Return values:

None

Example:

01 CALL fgl_ws_server_setNamespace("http://tempuri.org/")

fgl_ws_server_start() (version 1.3)

Purpose:

This function creates and starts the server. For development or testing purposes, you may start a Web Service server as a single server where only one request at a time will be able to be processed. For deployment, you may start a Web Service server with an application server able to handle several connections at one time using a load-balancing algorithm. The value of the parameter passed to the function determines which method is used.

Syntax:

FUNCTION fgl_ws_server_start(tcpPort VARCHAR)

Parameters:

tcpPort is a string representing either:

the socket port number (for a single Web Service server), or

the host and port value separated by a colon (for a Web Service server connecting to an application server). The value of port is an offset beginning at 6400.

Note: If the FGLAPPSERVER environment variable is set, the tcpPort value is ignored, and replaced by the value of FGLAPPSERVER.

Return values:

None

Examples:

To start a standalone Web Service server:

01 CALL fgl_ws_server_start("8080") # A single Server is listening  
02                                 # on port number: 8080

To start a Web Service server attempting to connect to an application server:

01 CALL fgl_ws_server_start("zeus:5") # The server attempt to connect
02                                   # to an application server located 
03                                   # on host zeus and listening  
04                                   # on the port number 6405

Possible runtime errors:

fgl_ws_server_publishFunction() (version 1.3)

Purpose:

This function publishes the given BDL function as a Web-Function on the Web.

Syntax:

FUNCTION fgl_ws_server_publishFunction(operationName VARCHAR, 
   inputNamespace VARCHAR, inputRecordName VARCHAR, 
   outputNamespace VARCHAR,outputRecord VARCHAR, 
   functionName VARCHAR)

Parameters:

operationName is the name by which the operation will be defined on the Web. The name is case sensitive.
inputNamespace is the namespace of the incoming operation message.
inputRecordName is the name of the BDL record representing the Web Function input message or "" if there is none.
outputNamespace is the namespace of the outgoing operation message.
outputRecord is the name of the BDL record representing the Web Function output message or "" if there is none.
functionName is the name of the BDL function that is executed when the Web Service engine receives a request with the operation name defined above.

Return values:

None

Example:

01 CALL fgl_ws_server_publishFunction(
02 "MyWebOperation",
03 "http://www.tempuri.org/webservices/","myfunction_input",
04 "http://www.tempuri.org/webservices/","myfunction_output",
05 "my_bdl_function")

Possible runtime errors:

fgl_ws_server_generateWSDL() (version 1.3)

Purpose:

This function generates the WSDL file according to the BDL-server program.

Syntax:

FUNCTION fgl_ws_server_generateWSDL(serviceName VARCHAR, 
   serviceLocation VARCHAR, fileName VARCHAR) 
RETURNING resultStatus INTEGER

Parameters:

serviceName is the name of the web service.
serviceLocation is the URL of the server.
fileName is the name of the file that will be generated.

Return value:

resultStatus is a status containing:

0 if the file has been correctly generated.

Any other values if the operation has failed.

Example:

01 DEFINE mystatus INTEGER
02
03 LET mystatus=fgl_ws_server_generateWSDL(
04 "CustomerService",
05 "http://localhost:8080",
06 "C:/mydirectory/myfile.wsdl")
07
08 IF mystatus=0 THEN
09   DISPLAY "Generation of WSDL done..."
10 ELSE
11   DISPLAY "Generation of WSDL failed!"
12 END IF

fgl_ws_server_process() (version 1.3)

Purpose:

This function waits for an incoming SOAP request for a given time (in seconds) and then processes the request, or returns, if there has been no request during the given time. If a DEFER INTERRUPT or DEFER QUIT instruction has been defined, the function returns even if it is an infinite wait.

Syntax:

FUNCTION fgl_ws_server_process(timeout INTEGER) 
   RETURNING resultStatus INTEGER

Parameter:

timeout is the maximum waiting time for an incoming request (or -1 for an infinite wait)

Return value:

resultStatus is a status containing:

0 — Request has been processed

-1 — Timeout has been reached

-2 — The application server asks the runner to shutdown

-3 — A client connection has been unexpectedly broken

-4 — An interruption has been raised

-5 — The HTTP header of the request was incorrect

-6 — The SOAP envelope was malformed

-7 — The XML document was malformed

Example:

01 DEFER INTERRUPT
02 DEFINE mystatus  INTEGER
03 LET mystatus=fgl_ws_server_process(5)# wait for 5 seconds   
04                                          # for incoming request  
05 IF mystatus=0 THEN
06   DISPLAY "Request processed."
07 END IF
08 IF mystatus=-1 THEN
09   DISPLAY "No request."
10 END IF
11 IF mystatus=-2 THEN # terminate the application properly 
12   EXIT PROGRAM       # if connected to application server
13 END IF
14 IF  mystatus=-3 THEN
15   DISPLAY "Client connection unexpectedly broken."
16 END IF
17 IF mystatus=-4 THEN
18   DISPLAY "Server process has been interrupted."
19 END IF
20 IF mystatus=-5 THEN
21   DISPLAY "Malformed or bad HTTP request received."
22 END IF
23 IF int_flag<>0 THEN
24   LET int_flag=0
25   EXIT PROGRAM
26 END IF

fgl_ws_server_setFault() (version 1.3)

Purpose:

This function can be called in a published Web-Function in order to return a SOAP fault string to the client at the end of the function's execution.

Syntax:

FUNCTION fgl_ws_server_setFault(faultMessage VARCHAR)

Parameter:

faultMessage is a string containing the SOAP Fault string that will be returned to the client.

Return values:

None

Example:

01 CALL fgl_ws_server_setFault(
    "The server is not able to manage this request.")

fgl_ws_server_getFault() (version 1.3)

Purpose:

This function retrieves the last fault string the user has set in a Web-Function, or an empty string if there is none.

Note: This function is only for testing the Web Services functions before they are published on the Web.

Syntax:

FUNCTION fgl_ws_server_getFault() 
    RETURNING faultMessage VARCHAR

Parameters:

None

Return value:

faultMessage is the string containing the SOAP Fault string.

Example:

01 DEFINE div_input RECORD
02			a INTEGER,
03			b INTEGER
04			END RECORD
05
06 DEFINE div_output RECORD
07			result INTEGER
08			END RECORD
09
10 FUNCTION TestServices()
11    DEFINE string VARCHAR(100)
12    ...
13    # Test divide by zero operation 
14    LET div_input.a=15
15    LET div_input.b=0
16    CALL service_operation_div()
17    LET string=fgl_ws_server_getFault()
18    DISPLAY "Operation div error: ", string
19    ...
20 END FUNCTION
21
22 FUNCTION service_operation_div()
23    ...
24    IF div_input.b = 0 THEN
25      CALL fgl_ws_server_setFault("Divide by zero")
26      RETURN
27    END IF
28    ...
29 END FUNCTION