/gen

Used With

/sti and /mwr =ws

Arguments

Options—string containing a comma-separated list of entity generation options.

Description

The /gen command line switch generates items that may provide assistance with creating the complex structures that are frequently used as web service parameters. It generates an XML example that documents what is required for each complex parameter, and generates modeled entities, where possible. For more information, see Generating Complex Parameters for Web Services .

The WSDL import uses the combination of the /nosig and the /dataonly flags to determine whether a signature is generated, and whether entities are generated for entity or occurrence parameters.

If /nosig has been specified, /gen="xml" produces an XML example only in the import log file. This can be useful to explore the WSDL file and determine which /gen options to use.

Just as the /dataonly flag can override the /nosig to generate entities, all other /gen options override the /nosig.

If the /bare switch is also used, no entities or XML are generated. No change in functionality is provided and only the signature is generated.

Inside a WSDL file, an XML schema describes the structure of the XML for the parameters of the operations. Using the schema, the WSDL import decides if the structure of the parameter is too complex to be mapped to a basic (scalar) type parameter or an entity or occurrence parameter as supported by the activate statement. This may be because complex types are nested within each other, or because a field or a group of fields can be repeating.

Model Groups

Model groups are a schema construct that describe a group of elements and the order in which they appear. Each occurrence of the group defined as one of the following:

• sequence—the elements appear in the same order as in the schema.

• choice—only one of the elements is allowed to appear.

• all—all the elements must appear zero or one times, but in any order.

A model group may be used to describe a complex type or a part of a type, which can produce an overlap between some options. For example, a complex type entity may be generated because the che (Choice model group entity) was specified even though the cte option (Complex type as entity) was not specified.

For entities generated for model groups and any elements, names are generated based on a sequential number, and have the form MODELGROUPSequenceNumber (or ANYSequenceNumber). The first entity does not get a number, but the following ones get a sequential number starting at 0 (zero); for example, any, any0, any1, and so on.

XML Parameter Template

When the xml option is specified, WSDL import generates an XML example. If /nosig is also specified, this XML appears in the import log file. Otherwise, it is stored in the parameter description in the Uniface signature. (It can be viewed in the Define a Parameter form of the Signature Editor.) This example XML is meant to document what is required for each complex parameter.

In the XML example:

• Any element or attribute that may have a character value (as opposed to just other elements), has its data type, without namespace, as the value. Thus, an element defined as numeric incorrectly receives a string value.

• An attribute with a fixed constraint will have that fixed value.

• Elements representing simple types may not be as simple as their name suggests. A simple type can be a single value, but may also be a list of values of the same data type or union of different data types, where the value will be of one of the allowed data types.

  The values may also be constrained in some way, for example, a decimal may be required to have 2 decimal places, or a string may only contain an enumerated value. When such complexity is encountered, comments are generated to clarify the allowed element content.

  Constraints are described in terms of XML Schema facets. These are largely self-explanatory, with names such as length or maxInclusive.

  XML Schema data types are not described at all. For more detail about facets and types. please see http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html

• Elements with simple content treat white space differently, depending on their data type. This is described by the whiteSpace XML Schema facet. By default:

  • Any simple type of string value preserves its white space

  • Non-string types and lists collapse the white space

  • Unions determine what happens to the white space on the basis of the sub data type.

  Uniface does not generate comments when the white space is handled according to the default for the data type.

• An entity, attribute, or model group that does not need to appear exactly once is preceded with a comment indicating the number of allowed occurrences, using minOccurs for the minimum number of occurrences and maxOccurs for the maximum number.

• For a model group, a comment is also added after the last element of the group indicating that the group has ended. The comment includes the type of model group and the associated constraint.

• If a cyclic complex type definition is detected, one repetition is allowed, but thereafter a comment is added indicating that the contents have been truncated due to a cyclic type.

• For the Document/Literal Wrapped type of web service, if a parameter repeats, an comment describing the repetition is added before the element.

ComplexType as Entity

The cte option generates an entity for each complex type that is too complex to be mapped to an entity or occurrence parameter. For an entity to be generated, it must contain at least one simple type. A complex type entity may also be generated if its model group is of a type that has been requested.

• Each complexType becomes an entity containing only the elements that map to scalar data type fields.

• Each embedded complexType becomes an entity in its own right.

• Each element attribute becomes a field, including the wildcard anyAttribute.

Repeating fields and parameters as entity

The rfe option generates an entity with one field for each simple type element that can have multiple occurrences. The entity and the field names are the same as the element name. If not specified, these elements are treated as a simple type and added as a field in an enclosing entity.

For a Document Literal Type web service, when a parameter is a simple type but is defined as repeating, the rfe option generates an entity, preceded by a comment describing the repetition. when a parameter is a simple type but is defined as repeating

Repeating Model Group as Entity

The rge option generates an entity for each model group that is allowed to have multiple occurrences. The contents of a model group can be simple or complex, so only the simple types are added to the model group entity. There must be at least one simple type, and for the others, the specified /gen options apply.

The name of the entity is generated based on a sequential number. Unless overridden by the /mod command line switch, the model name is generated from the namespace of the enclosing type.

If this option is not specified, it is handled as if it was not repeating, meaning that simple types are placed in the enclosing type or group entity.

Choice as Entity

For model groups that are defined as a group of choices, the che option generates an entity containing all the elements, even though only one of them is allowed to appear.

The rge and che options overlap, so if it is a repeating choice group, either option causes an entity to be generated.

If this option is not specified, the simple types are added to the enclosing type or group entity.

Any as Entity

The ane option generates an entity for each any element. The any element is a wildcard element that allows more or less any sort of content. It has a default type of the anyType. Although this is a complex type, an entity is not generated unless this option is set.

If this option is not specified, the any element is treated as a simple type. If multiple any elements exist in the same complex type, the normal field name resolution is used to avoid conflicts.

The anyType is defined as having mixed content. It has one attribute, the anyAtribute, and contains one element, the any element. This is a cyclic type definition.

The name of the entity is generated based on a sequential number. All any elements result in distinct entity definitions, each containing one field corresponding to the anyAttribute.

Entity Relationships

The rel option creates relationships between the generated entities. For each generated entity, a field is selected for use as the primary key. The schema construct of identity constraints are not used. Selection is based on a field occurring exactly once and being of a Uniface type that is neither boolean nor raw. If such a field is not found, the first field is chosen.

All entities that are generated from embedded complex types get an extra field (a foreign key field) with the form fk_EntityName_PrimaryKeyFieldName. The EntityName is the name of the entity from which the primary key field came.

Once the foreign key fields have been generated, a one-to-many relationship is generated. In these relationships, the Index on Foreign Key box is ticked so that when the table is created, indexes will also be generated in the DBMS for efficient retrieval. No key is explicitly defined in the Uniface repository for the foreign key.

Primary Key Field

The pkf option forces the generation of an entity which otherwise would not be generated, and allows a relationship to be defined.

Using /gen

ide /sti /mwr=ws /gen="cte,xml" http://www.WebSite.com/aWebService/aWebService.wsdl