Back to Contents

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.

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)
• 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:

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

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:

• -15504: PORT_ALREADY_USED
• -15514: PORT_NOT_NUMERIC
• -15515: NO_AS_FOUND
• -15516: LICENSE_ERROR

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:

• -15503: FUNCTION_ALREADY_EXISTS
• -15501: FUNCTION_ERROR
• -15502: FUNCTION_DECLARATION_ERROR
• -15512: INPUT_VARIABLE_ERROR
• -15513: OUTPUT_VARIABLE_ERROR
• -15503: BDL_XML_ERROR
• -15518: INPUT_NAMESPACE_MISSING
• -15519: OUTPUT_NAMESPACE_MISSING
  

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