4D v13.4

SOAP DECLARATION

Home

 
4D v13.4
SOAP DECLARATION

SOAP DECLARATION 


 

SOAP DECLARATION ( variable ; type ; input_output {; alias} )  
Parameter Type   Description
variable  Variable in Variable referring to an incoming or outgoing SOAP argument
type  Longint in 4D type to which the argument points
input_output  Longint in 1 = SOAP Input, 2 = SOAP Output
alias  String in Name published for this argument during SOAP exchanges

The SOAP DECLARATION command explicitly declares the type of parameters used in a 4D method published as a Web Service.

When a method is published as a Web Service, the standard parameters $0, $1... $n describe the parameters of the Web Service to the outside world (more particularly in the WSDL file). The SOAP protocol requires that parameters be explicitly named; 4D uses the names “FourD_arg0, FourD_arg1 ... FourD_argn” by default.

This default operation can nevertheless prove to be problematic for the following reasons:

  • It is not possible to declare $0 or $1, $2, etc. as an array. Therefore, it is necessary to use pointers; however, in this case, the type of values must be known for the generation of the WSDL file.
  • It can be useful or necessary to customize the parameter names (incoming and outgoing).
  • You may want to use parameters such as XML structures and DOM references.
  • It may also be necessary to retur values with a size greater than 32 KB (limit for Text arguments in databases that are in non-Unicode mode).
  • Finally, this operation makes it impossible to return more than one value per RPC call (in $0).

The SOAP DECLARATION command lets you be free from these limits. You can execute this command for each incoming and outgoing parameter to assign it a name and a type.

Note: Even when the this command is used, it is still necessary to declare 4D variables and arrays in the Compiler_Web method using commands of the “Compiler” theme.

In variable, pass the 4D variable to be referred to when calling the Web Service.

Warning: You can only refer to process variables or 4D method arguments ($0 to $n). Local and interprocess variables cannot be used.

By default, because only Text type arguments can be used, the SOAP server responses are limited to 32 KB in databases that are in non-Unicode mode. However, it is possible to return SOAP arguments with a size greater than 32 KB, using BLOBs. To exceed this limit, you simply need to declare the arguments as BLOBs before calling the SOAP DECLARATION command (see example 4).

Note: On the client side, if you subscribe to this type of Web Service with 4D, the Web Services Wizard will of course generate a Text type variable. To be able to use it, you just need to re-type this return variable as a BLOB in the proxy method.

In type, pass the corresponding 4D type. Most types of 4D variables and arrays can be used. You can use the following predefined constants, located in the “Field and Variable Types” theme, as well as, for XML types, two constants of the Web Services (Server) theme:

Constant Type Value
Boolean array Longint 22
Date array Longint 17
Integer array Longint 15
Is BLOB Longint 30
Is Boolean Longint 6
Is Date Longint 4
Is Integer Longint 8
Is LongInt Longint 9
Is Real Longint 1
Is String Var Longint 24
Is Text Longint 2
Is Time Longint 11
LongInt array Longint 16
Real array Longint 14
String array Longint 21
Text array Longint 18

Constant Type Value
Is DOM reference Longint 37
Is XML Longint 36
In input_output, pass a value indicating whether the processed parameter is “incoming” (i.e. corresponding to a value received by the method) or “outgoing” (i.e. corresponding to a value returned by the method). You can use the following predefined constants, located in the Web Services (Server) theme:

Constant Type Value
SOAP Input Longint 1
SOAP Output Longint 2

You can declare variables of the "XML structure" and "DOM reference" type, both incoming and outgoing, via the Is XML and Is DOM reference constants. When parameters of this type are specified, no processing or encoding is applied to them and the data are transmitted "as is" (see example 5).

  • Outgoing parameters:
    • Is XML indicates that the parameter contains an XML structure,
    • Is DOM reference indicates that the parameter contains the DOM reference of an XML structure. In this case, inserting the XML structure into the SOAP message is equivalent to executing the DOM EXPORT TO VAR command.

Note: In the case of DOM references used as outgoing parameters, it is recommended to use global references, created, for example, on startup and closed when the application is closed. In fact, a DOM reference created within the Web Service itself cannot be closed with DOM CLOSE XML, otherwise the Web Service no longer returns anything. Multiple calls to the Web Service therefore involve creating multiple unclosed DOM references, which can lead to memory saturation

  • Incoming parameters:
    • Is XML indicates that the parameter must receive an XML argument sent by the SOAP client.
    • Is DOM reference indicates that the parameter must receive the DOM reference of an XML structure corresponding to the XML argument sent by the SOAP client.
  • Modification of the WSDL: These XML structures will be declared by 4D as the "anyType" type (undetermined) in the WSDL. If you want to type an XML structure precisely, you must save the WSDL file and manually add the desired data schema in the <types> section of the WSDL

Incoming SOAP arguments referred to using 4D variables (and not 4D method arguments) must first be declared in the COMPILER_WEB project method. In fact, the use of process variables in Web Services methods requires that they be declared before the method is called. The COMPILER_WEB project method is called, if it exists, for each SOAP request accepted. By default, the COMPILER_WEB method does not exist. You must specifically create it.

Note that the COMPILER_WEB method is also called by the 4D Web server when receiving “conventional” Web requests of the POST type (see SPELL GET DICTIONARY LIST section).

In alias, pass the name of the argument as it must appear in the WSDL and in the SOAP exchanges.

Warning: This name must be unique in the RPC call (both input and output parameters taken together), otherwise, only the last declaration will be taken into account by 4D.

Note: The argument names must not begin with a number nor contain spaces. Moreover, to avoid any risks of incompatibility, it is recommended to not use extended characters (such as accented characters).
If the alias parameter is omitted, 4D will use, by default, the name of the variable or FourD_argN for the 4D method arguments ($0 to $n).

Note: The SOAP DECLARATION command must be included in the method published as a Web Service. It is not possible to call it from another method.

This example specifies a parameter name:

  ` In the COMPILER_WEB method
 C_LONGINT($1)
 
  ` In the Web Service method
  ` During generation of the WSDL file and SOAP calls, the word
  ` zipcode will be used instead of fourD_arg1
 SOAP DECLARATION($1;Is LongInt;SOAP Input;"zipcode")

This example retrieves an array of zip codes in the form of longints:

  `In the COMPILER_WEB method
 ARRAY LONGINT(codes;0)
 
  `In the Web service method
 SOAP DECLARATION(codes;LongInt array;SOAP Input;"in_codes")

This example refers to two return values without specifying an argument name:

 SOAP DECLARATION(ret1;Is LongInt;SOAP Output)
 SOAP DECLARATION(ret2;Is LongInt;SOAP Output)

This example allows the 4D SOAP server to return an argument with a size greater than 32 KB in databases in non-Unicode mode:

 C_BLOB($0)
 SOAP DECLARATION($0;Is Text;SOAP Output)


Note the type Is Text (and not Is BLOB). This allows the argument to be correctly processed.

This example illustrates the results of different types of declarations:

 ALL RECORDS([Contact])
 
  `Build an XML structure from the Contacts selection and store the XML in a BLOB
 C_BLOB(ws_vx_xmlBlob)
 getContactsXML(->ws_vx_xmlBlob)
  `Retrieve the XML structure in a text variable
 C_TEXT(ws_vt_xml)
 ws_vt_xml:=BLOB to text(ws_vx_xmlBlob;UTF8 Text without length)
  `Retrieve a DOM reference to the XML structure
 C_TEXT(ws_vt_xmlRef)
 ws_vt_xmlRef:=DOM Parse XML variable(ws_vt_xml)
 
  `Test the various declarations
 SOAP DECLARATION(ws_vx_xmlBlob;Is BLOB;SOAP Output;"contactListsX")
  `The XML is converted into Base64 by 4D
 
 SOAP DECLARATION(ws_vt_xml;Is Text;SOAP Output;"contactListsText")
  `The XML is converted into text by 4D (< > become entities)
 
 SOAP DECLARATION(ws_vt_xml;Is XML;SOAP Output;"xmlContacts")
  `The XML is passed as XML text
 
 SOAP DECLARATION(ws_vx_xmlBlob;Is XML;SOAP Output;"blobContacts")
  `The XML is passed as an XML BLOB
 
 SOAP DECLARATION(ws_vt_xmlRef;Is DOM reference;SOAP Output;"contactByRef")
  `The XML is passed as a reference

 
PROPERTIES 

Product: 4D
Theme: Web Services (Server)
Number: 782

 
INDEX

Alphabetical list of commands

 
HISTORY 

Modified: 4D v11 SQL Release 2

 
SEE ALSO 

Is data file locked
SOAP Get info
SOAP SEND FAULT