soap append

soap append soaphandle ?attribute value?...

This is a variant of the soap set command. The difference is that the supplied data is appended to the current attribute value instead of replacing it. In case appending is not a possible operation, the result is the same as using soap set .

The set of supported attributes is explained in the paragraph on soap set .

soap create

soap create ?attribute value?...

Create a new SOAP object. The return value is the object handle. If no extra attributes are specified, an empty object with default settings is created. Processing of specified optional attribute/value pairs is performed in as an identical fashion to the soap set command.

soap delete

soap delete ?soaphandle?...

soap delete all

Destroy one or more SOAP objects. The special word all can be used to remove all SOAP objects currently defined in the interpreter.

For the sake of consistency with the commands for other objects, soap close is an alias to this command.

The return value is the number of successfully deleted SOAP objects.

soap error

soap error soaphandle ??message? channel? ?code? ?factor?

Send a properly formatted SOAP error message over a Tcl channel to a client, or at least prepare it. If any of the optional arguments behind the channel argument are provided, they are processed like soap set commands and change the internal attributes of the object.

In the generated message, the message, code and factor values are wrapped into XML tags of type faultstring , faultcode and faultfactor , respectively. Usually, the factor value should be set to the URI of the service, which could be stored in the uri attribute of the SOAP object. This core information is then embedded into a standard SOAP fault envelope. If no channel argument or an empty string is specified, and the internal channel of the SOAP object is undefined, no data is transmitted over the channel, but the message is still formatted. If a valid channel was specified, or the SOAP object has a valid internal channel, the message is immediately transmitted.

The return value of the command is the complete SOAP error message, with header and body. The internal header and body fields of the SOAP object are also updated and allow subsequent individual retrieval of these components.

soap find

soap find soaphandle taglist ?mode? ?contentflags?

Find the contents and/or attributes of specific XML tags in a message. The computation of a parse tree (see soap parse command) is a prerequisite for this function. If a parse tree does not yet exist, but the SOAP object has body data, an automatic attempt is made to execute a parse of the full message body data.

The command returns data found inside the first of potentially multiple query tags which matches in case-sensitive fashion a tag in the parse tree, which is traversed depth-first.

The mode argument determines the reporting mode. It can be one of

• first
  Find the first instance of tag and return single data item.
• next
  Find the next instance of tag after current position, or begin of message if this is the first query, and return single data item.
• a numerical index
  Find the nth instance of the tag and return single data item. The index starts with zero.
• all
  Return all matching tag contents as a list of data item information. This is the default mode.

The type of tag content reported can be configured by the contentflags argument. The argument can be an arbitrary list made from the words

• tag
  The name of the tag itself.
• attributes
  The attributes of the tag, as name/value dictionary.
• chardata
  The character data in the tag, excluding embedded inner tags, possibly trimmed (see trimmed flag word).
• children
  If set, include the same data as for the matched tag recursively for all its children, as nested lists.
• trimmed
  Remove left and right white space from the returned chardata value.
• noleafchildren
  If children is set, omit output of an empty children list if a node has no children.

The default output selection is just chardata . If multiple content flags are selected, the order of the elements in an item output list is tag , attributes , chardata and finally children . If a query fails to yield any results, an empty string is returned. In reporting mode all , the item output lists are themselves list elements of the overall result list.

This command is not SOAP -specific but can work in principle on any XML data, for example Entrez eutils output.

soap get

soap get soaphandle attribute

Query the value of an attribute of a SOAP object. The list of recognized attributes is explained in the paragraph on the soap set command.

The return value of the command is the value of the attribute.

soap list

soap list ?pattern?

Return a list of all currently existing soap objects in the interpreter. If desired, the list can be filtered by a string pattern.

soap parse

soap parse soaphandle ?starttag? ?class? ?data?

Parse an XML message stored in the body attribute of the object and create the parse tree which is the prerequisite for retrieval of message content via the soap find command. If a data argument is supplied, it replaces the body data of the object.

By default, or when the start tag argument is set to an empty string, the complete message is parsed. Optionally, processing can be limited to a subsection of the full data that starts with the specified tag. In that case, only the content between the first opening and closing tags matching the supplied start tag is analyzed, and the argument replaces the tag attribute of the SOAP object. In case of multiple tags with the same name in the parsed data, an additional class attribute can be specified as a second element. If this optional filtering argument is used, the first tag block matching both the tag name and having a matching class attribute is extracted and parsed. If the class argument is omitted, or empty, no class filtering is performed.

The result of the command is the parse tree in nested list representation. This is the same data as the parsetree attribute which can be queried via soap get .

soap read

soap read soaphandle ?channel?

Read a message with a MIME header from a channel. If the channel argument is not supplied, the internally configured SOAP object channel is used. The internal header and body attributes of the object are updated when the read succeeds. Note that this command works with any communication which uses a MIME header and body data. It is not limited to reading SOAP messages, or even plain XML data.

The reader supports chunked data transmission.

The return value of the command is the received body text. In most applications, this command is followed by a soap parse command, and then multiple soap find commands.

soap reformat

soap reformat soaphandle ?string?

Pretty-print an XML blob, with properly indented nested tags for easy visual inspection. If no explicit string is specified, the current body attribute value of the soap object is used. The return value of the command is the reformatted content. The original data is not changed.

This command assumes that the input is not pre-formatted. It does not attempt to remove existing line feeds for formatting whitespace on the input, but rather adds it own formatting on top.

soap request

soap request soaphandle ?method? ?channel? ?parameters? ?uri?

Call a SOAP handler on a remote server, or at least prepare the message to do that. If any of the optional arguments with the exception of the channel argument are provided, they are processed like soap set commands and change the internal attributes of the object. If the uri argument is not supplied, and the SOAP object has no configured uri attribute, a default URI to be used as part of the HTTP POST instruction in the header is constructed from the host , port and method attributes. This URI is not directly used to open a communication channel, though - the Tcl transmission channel can be opened by any suitable means.

If the channel argument is not supplied, or written as an empty string, and the object has no valid internal handle, the message is just assembled. Otherwise, it is transmitted directly. Using a channel argument does not update the internal channel attribute of the object.

The return value of the command is the complete SOAP error message, with header and body. The internal header and body fields of the SOAP object are also updated and allow subsequent individual retrievals of these components.

Note that this command just sends the request, but does not wait for or read the server response. Use the soap read command for this purpose.

soap respond

soap respond soaphandle responsedata ?channel? ?method? ?namespace?

Send a properly formatted SOAP response message over a Tcl channel to a client, usually as a response to receiving a SOAP request message from that client. If any of the optional arguments behind channel are provided, they are processed like soap set commands and change the internal attributes of the object

In the generated message, the responsedata value is wrapped into an XML tag of type < methodResponse >, where method is replaced by the name of the configured SOAP method. This core information is then embedded into a standard SOAP envelope and transmitted over the channel. If no channel argument is given, and the internal channel of the SOAP object is undefined, the message is just formatted, but not transmitted.

The return value of the command is the complete SOAP message, with header and body. The internal header and body fields of the SOAP object are also updated and allow subsequent individual retrievals of these components.

soap set

soap set soaphandle ?attribute value?..

Set one or more attributes of a SOAP object. Since this paragraph is also referenced from the soap get subcommand, the attribute set listed here includes attributes which cannot be set, or for which setting them to any scripted value does not usually make sense.

The currently supported set of attributes is:

• body
  The body part of the last received SOAP message. This attribute is not usually set.
• bodylength
  The length of the body, in bytes. This is a read-only attribute.
• channel
  The communication channel associated with the SOAP object. This is a standard Tcl channel handle. It is possible to set it to an empty string, which indicates that no channel is set.
• errorcode
  The error code from the last XML parsing step as integer value. If no error occurred, the value is 0.
• errorcolumn
  The column the XML parser detected the last error.
• errorfactor
  The factor leading to an error, either as received from a SOAP message, or set in preparation of sending an error message. Standard practice is to send the URI of the failed service in this field.
• errorline
  The line the XML parser detected the last error.
• errormsg
  The message of a SOAP error, either as extracted from a SOAP message, or set in preparation of sending an error message.
• header
  The header part of the last received SOAP message. This attribute is not usually set.
• headerlength
  The length of the header, in bytes. This is a read-only attribute.
• host
  The remote host the SOAP object communicates with.
• method
  The method identification of either the last received SOAP message, or set in preparation to send a message.
• namespace
  The SOAP method namespace. It can be set to an empty string in order to avoid using method namespace attributes in sent XML messages altogether. The namespace suppression only applies to the method section. The overall SOAP envelope will still contain a standard set of namespace references.
• parameters
  The SOAP method parameters. If queried, this is a dictionary of name/value pairs. In order to set these, a properly formatted dictionary must be supplied. The formatting is the same as for the parameters attribute of property definitions.
• parsetree
  A nested list representation of parse tree generated by the last successful XML content parse by means of the soap parse command. This is a read-only attribute, and primarily useful for debugging.
• port
  The port the SOAP object uses for network communication. The default is 80, the standard HTTP port.
• response
  The response part of the last SOAP message, in parse tree representation. This is a read-only attribute.
• result
  The pure method invocation result data extracted from the last SOAP message. This is a read-only attribute.
• tag
  The current start tag for parsing a subsection of XML message content, see soap parse command.
• uri
  The URI associated with a SOAP service.

soap subcommands

soap subcommands

This command returns a list of all the subcommands of the soap command.