SOAP DECLARATION

version 2003

SOAP DECLARATION (variable; type; input_output{; alias})

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

The SOAP DECLARATION command is used to explicitly declare 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 are used to 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; 4th Dimension 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 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.

• Next, it can be useful or necessary to customize the parameter names (incoming and outgoing).

• Finally, this operation makes it impossible to return more than one value per RPC call (in $0).

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

Note: Even if the SOAP DECLARATION command is used, it is always necessary to declare 4D variables 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.

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:

Note: The following constants are not used in SOAP methods: Is Alpha Field, Is Pointer, Array 2D, Picture array, Pointer array, Is Picture, Is Subtable, Is Undefined.

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:

COMPILER_WEB method: 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 Web Services, Special URLs and Form Actions 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: In conformity with the XML standard for marker names, the argument names must NOT contain spaces or extended characters. Only the following Latin characters may be used: ([A-Za-z0-9._] | '-')*.

If the alias parameter is omitted, 4th Dimension 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.

(1) This example specifies a parameter name:

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

(2) This example is used to retrieve an array of zip codes in the form of longints:

   ARRAY LONGINT(codes;0)
   SOAP DECLARATION(codes;LongInt array;SOAP Input;"in_codes")

(3) This example is used to refer to two return values without specifying an argument name:

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

Get SOAP info, Is data file locked, SEND SOAP FAULT.

Field and Variable Types and Web Services themes.