DFHWS2LS: WSDL to high level language conversion

Cataloged procedure DFHWS2LS generates a high level language data structure and a Web service binding file from a Web service description. You can use DFHWS2LS when you expose a CICS® application program as a service provider or when you construct a service requester.

Job control statements for DFHWS2LS

JOB
Initiates the job.
EXEC
Specifies the procedure name (DFHWS2LS).

DFHWS2LS requires sufficient storage to run a Java™ virtual machine (JVM). You are advised to specify REGION=0M on the EXEC statement.

INPUT.SYSUT1 DD
Specifies the input. The input parameters are usually specified in the input stream. However, they can be defined in a data set, or in a member of a partitioned data set.

Symbolic parameters

The following symbolic parameters are defined in cataloged procedure DFHWS2LS:
JAVADIR=path
Specifies the name of the Java directory that is used by DFHWS2LS. The value of this parameter is appended to /usr/lpp/ giving a complete path name of /usr/lpp/path.
Normally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the JAVADIR parameter.
Start of changePATHPREF=prefixEnd of change
Start of changeSpecifies an optional prefix that extends the HFS directory path used on other parameters. The default is the empty string.End of change
Start of changeNormally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the JAVADIR parameter.End of change
TMPDIR=tmpdir
Specifies the location of a directory in HFS that DFHWS2LS uses as a temporary work space. The user ID under which the job runs must have read and write permission to this directory.
The default value is /tmp.
TMPFILE=tmpprefix
Specifies a prefix that DFHWS2LS uses to construct the names of the temporary workspace files.
The default value is WS2LS.
USSDIR=path
Specifies the name of the CICS TS directory in the UNIX system services HFS. The value of this parameter is appended to /usr/lpp/cicsts/ giving a complete path name of /usr/lpp/cicsts/path.
Normally, you do not need to specify this parameter; the default value is the value that was supplied to the CICS installation job (DFHISTAR) in the USSDIR parameter.
Start of changeSERVICE=valueEnd of change
Start of changeUse this parameter only when directed to do so by IBM® support.End of change

The temporary work space

DFHWS2LS creates the following three temporary files during execution:
  • tmpdir/tmpprefix.in
  • tmpdir/tmpprefix.out
  • tmpdir/tmpprefix.err
where
  • tmpdir is the value specified in the TMPDIR parameter
  • tmpprefix is the value specified in the TMPFILE parameter.
The default names for the files (when TMPDIR and TMPFILE are not specified), are:
  • /tmp/WS2LS.in
  • /tmp/WS2LS.out
  • /tmp/WS2LS.err
Important: DFHWS2LS does not lock access to the generated HFS file names. Therefore, if two or more instances of DFHWS2LS run concurrently, and use the same temporary workspace files, there is nothing to prevent one job overwriting the workspace files while another job is using them. This can lead to unpredictable failures.

Therefore, you are advised to devise a naming convention, and operating procedures, that will avoid this situation. For example, you can use the system symbolic parameter SYSUID to generate workspace file names that are unique to an individual user.

These temporary files are deleted before the end of the job.

Input parameters for DFHWS2LS

If you need any help understanding this syntax diagram, see Syntax notation.

Read syntax diagramSkip visual syntax diagram
>>-PDSLIB=value--+-------------+--+--------------+-------------->
                 '-PDSCP=value-'  '-REQMEM=value-'   

>--+---------------+-------------------------------------------->
   '-RESPMEM=value-'   

>--+-+-LANG=COBOL----------+--------------------------------------------+-->
   | +-LANG=PLI-ENTERPRISE-+                                            |   
   | '-LANG=PLI-OTHER------'                                            |   
   '-+-LANG=C---+--+--------------------------------------------------+-'   
     '-LANG=CPP-'  |             .-DFHREQUEST--.   .-DFHRESPONSE--.   |     
                   '-STRUCTURE=(-+-+---------+-+-,-+-+----------+-+-)-'     
                                   '-request-'       '-response-'           

>--+---------------------------------------------------------------------------------------------------------+-->
   |                               .-PGMINT=CHANNEL--+--------------+-.                                      |   
   |                               |                 '-CONTID=value-' |                                      |   
   '-PGMNAME=value--+-----------+--+----------------------------------+--+------------------+--+-----------+-'   
                    '-URI=value-'  '-PGMINT=COMMAREA------------------'  '-TRANSACTION=name-'  '-USERID=id-'     

>--WSBIND=value--WSDL=value------------------------------------->

   .-MAPPING-LEVEL=1.0----------------------------.   
>--+----------------------------------------------+------------->
   +-MAPPING-LEVEL=1.1----------------------------+   
   '-MAPPING-LEVEL=1.2--| Advanced data mapping |-'   

   .-MINIMUM-RUNTIME-LEVEL=MINIMUM-.   
>--+-------------------------------+---------------------------->
   +-MINIMUM-RUNTIME-LEVEL=1.0-----+   
   +-MINIMUM-RUNTIME-LEVEL=1.1-----+   
   +-MINIMUM-RUNTIME-LEVEL=1.2-----+   
   '-MINIMUM-RUNTIME-LEVEL=CURRENT-'   

>--+-----------------------------------------+--+--------------------------+--+--------------------------+-->
   '-HTTPPROXY=-+-domain name-+-:port number-'  '-HTTPPROXY-USERNAME=value-'  '-HTTPPROXY-PASSWORD=value-'   
                '-IP address--'                                                                              

>--+---------------+--+-------------+--LOGFILE=value------------>
   '-BINDING=value-'  '-CCSID=value-'                  

>--+----------------------+------------------------------------><
   |               .-NO-. |   
   +-SYNCONRETURN=-+----+-+   
   '-SYNCONRETURN=YES-----'   

Advanced data mapping

                          .-CHAR-VARYING-LIMIT=32767-.   
|--+-------------------+--+--------------------------+---------->
   +-CHAR-VARYING=NO---+  '-CHAR-VARYING-LIMIT=value-'   
   +-CHAR-VARYING=NULL-+                                 
   '-CHAR-VARYING=YES--'                                 

   .-CHAR-MULTIPLIER=1-----.   
>--+-----------------------+------------------------------------>
   '-CHAR-MULTIPLIER=value-'   

   .-DEFAULT-CHAR-MAXLENGTH=255---.   
>--+------------------------------+-----------------------------|
   '-DEFAULT-CHAR-MAXLENGTH=value-'   

Parameter use

Parameter descriptions

BINDING=value
If the Web service description contains more than one <binding> element, use this parameter to specify which one is to be used to generate the language structure and Web service binding file. Specify the value of the name attribute that is used on the <binding> element in the Web service description.
Start of changeCCSID=valueEnd of change
Start of changeSpecifies the CCSID that is used at run time to encode character data in the application data structure. The value of this parameter overrides the value of the LOCALCCSID system initialization parameter. The value must be an EBCDIC CCSID that is supported by Java and z/OS conversion services. If you do not specify this parameter, the application data structure is encoded using the CCSID specified in the system initialization parameter.

You can use this parameter with any mapping level. However, if you want to deploy the generated files, you must apply APAR PK23547 to the CICS region to achieve the minimum runtime level of code to install the Web service binding file.

End of change
CHAR-MULTIPLIER=1|value
Specifies the number of bytes to allow for each character when the mapping level is 1.2. The value of this parameter can be a positive integer in the range of 1 to 2147483647. All nonnumeric character-based mappings, are subject to this multiplier. Binary, numeric, zoned and packed decimal fields are not subject to this multiplier.

This parameter can be useful if, for example, you are planning to use DBCS characters where you could opt for a multiplier of 3 to allow space for potential shift-out and shift-in characters around every double byte character at run time.

CHAR-VARYING=NO|NULL|YES
Specifies how variable length character data is mapped. Variable length character data is where the minimum and maximum length of a field is different. This parameter can only be used when the mapping level is 1.2. If you do not specify this parameter, the default mapping depends on the language that is specified. These defaults are described in the mappings for each language and XML schema in High level language and XML schema mapping. The options that you can select are:
NO
Variable length character data is mapped as fixed length strings.
NULL
Variable length character data is mapped to null terminated strings.
YES
Variable length character data is mapped to a CHAR VARYING data type in PL/I. In the COBOL, C and C++ languages, variable length character data is mapped to an equivalent representation that comprises of two related elements - data length and the data.
Start of changeCHAR-VARYING-LIMIT=32767|valueEnd of change
Start of changeSpecifies the maximum size of variable length character data that is mapped to the language structure. If the character data is larger than the value specified in this parameter, it is mapped to a container and the container name is used in the generated language structure. The value can range from 0 to the default 32767 bytes.

This parameter can only be used when the mapping level is 1.2.

End of change
CONTID=value
In a service provider, specifies the name of the container that holds the top level data structure used to represent a SOAP message.

Start of changeThe length of the container that CICS passes to the target application program is the greater of the lengths of the request container and the response container.End of change

Start of changeDEFAULT-CHAR-MAXLENGTH=255|valueEnd of change
Start of changeSpecifies the default field length of character data in characters for mappings where no length is implied in the Web service description document. The value of this parameter can be a positive integer in the range of 1 to 2147483647.

You can only use this parameter when the mapping level is 1.2.

End of change
HTTPPROXY={domain name|IP address}:port number
If your WSDL contains references to other WSDL files that are located on the internet, and the system on which you are running DFHWS2LS uses a proxy server to access the internet, specify the domain name or IP address, and port number, of the proxy server. For example:
HTTPPROXY=proxy.example.com:8080

In other cases, this parameter is not required.

Start of changeHTTPPROXY-USERNAME=valueEnd of change
Start of changeSpecifies the HTTP proxy username that should be used in conjunction with HTTPPROXY-PASSWORD if the system on which you are running DFHWS2LS uses a HTTP proxy server to access the Internet, and the HTTP proxy server uses basic authentication. You can only use this parameter when you also specify HTTPPROXY.End of change
Start of changeHTTPPROXY-PASSWORD=valueEnd of change
Start of changeSpecifies the HTTP proxy password that should be used in conjunction with HTTPPROXY-USERNAME if the system on which you are running DFHWS2LS uses a HTTP proxy server to access the Internet, and the HTTP proxy server uses basic authentication. You can only use this parameter when you also specify HTTPPROXY.End of change
LANG=COBOL
Specifies that the programming language of the high level language structure is COBOL.
LANG=PLI-ENTERPRISE
Specifies that the programming language of the high level language structure is Enterprise PL/I.
Start of changeLANG=PLI-OTHEREnd of change
Start of changeSpecifies that the programming language of the high level language structure is a level of PL/I other than Enterprise PL/I.End of change
LANG=C
Specifies that the programming language of the high level language structure is C.
LANG=CPP
Specifies that the programming language of the high level language structure is C++.
LOGFILE=value
The fully qualified HFS name of the file into which DFHWS2LS writes its activity log and trace information. DFHWS2LS creates the file (but not the directory structure) if it does not already exist.

Normally you will not need to use this file, but it may be requested by the IBM service organization if you encounter problems with DFHWS2LS.

Start of changeMAPPING-LEVEL={1.0|1.1|1.2}End of change
Start of changeSpecifies the level of mapping that DFHWS2LS should use when generating the Web service binding file and language structure. This parameter is available when you apply APAR PK15904. You also need to apply APAR PK23547 if you want to use the 1.2 mapping level option. The options you can select are:
1.0
This is the default mapping level.
1.1
XML attributes, <list> data types, and <union> data types are mapped to the language structure. Character and binary data that has a maximum length of more than 32,767 bytes is mapped to a container. The container name is created in the language structure.
1.2
Use the parameters CHAR-VARYING and CHAR-VARYING-LIMIT to control how character data is mapped and processed at run time. If you do not specify either of these parameters, binary and character data that has a maximum length less than 32768 bytes is mapped to a VARYING structure for all languages except C++, where character data is mapped to a null terminated string.
For details of what is supported at each level of mapping, see Mapping levels for the CICS Web services assistant.End of change
Start of changeMINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|CURRENT}End of change
Start of changeSpecifies the minimum CICS runtime environment that the Web service binding file can be deployed into. If you select a level that does not match the other parameters that you have specified, you receive an error message. The options you can select are:
MINIMUM
The lowest possible runtime level of CICS is allocated automatically given the parameters that you have specified.
1.0
The generated Web service binding file deploys successfully into a CICS TS 3.1 region that does not have APARs PK15904 and PK23547 applied. You cannot specify the CCSID or MAPPING-LEVEL parameter, or any other optional parameters that rely on the MAPPING-LEVEL parameter.
1.1
The generated Web service binding file deploys successfully into a CICS TS 3.1 region that has at least APAR PK15904 applied. You cannot specify the CCSID parameter or use a mapping level of 1.2 for the MAPPING-LEVEL parameter. You cannot specify any optional parameters that rely on the 1.2 level of mapping.
1.2
The generated Web service binding file deploys successfully into a CICS TS 3.1 region that has both APAR PK15904 and PK23547 applied. You can use any optional parameter at this level.
CURRENT
The generated Web service binding file deploys successfully into a CICS region at the same runtime level as the one you are using to generate the Web service binding file.
End of change
PDSLIB=value
Specifies the name of the partitioned data set that contains the generated high level language. The data set members used for the request and response are specified in the REQMEM and RESPMEM parameters respectively.
Start of changePDSCP=valueEnd of change
Start of changeSpecifies the code page used in the partitioned data set members specified in the REQMEM and RESPMEM parameters, where value is a CCSID number or a Java code page number. If this parameter is not specified, then the z/OS® UNIX System Services code page is used. For example, you could specify PDSCP=037.End of change
PGMINT=CHANNEL|COMMAREA
For a service provider, specifies how CICS passes data to the target application program:
CHANNEL
CICS uses a channel interface to pass data to the target application program.
COMMAREA
CICS uses a communication area to pass data to the target application program.
This parameter is ignored when the output from DFHWS2LS is used in a service requester.

Start of changeWhen the target application program has processed the request, it must use the same mechanism to return the response. If the request was received in a communication area then the response must be returned in the communication area; if the request was received in a container, the response must be returned in a container. The length of the communication area or container that CICS passes to the target application program is the greater of the lengths of the request communication area or container and the response communication area or container.End of change

PGMNAME=value
This parameter specifies the name of a CICS program.
When DFHWS2LS is being used to generate a Web service binding file that will be used in a service provider, this parameter must be supplied. It specifies the name of the application program that is being exposed as a Web service.
When DFHWS2LS is being used to generate a Web service binding file that will be used in a service requester, this parameter must be omitted.
REQMEM=value
Specifies a 1 - 6 character prefix that DFHWS2LS uses to generate the names of the partitioned data set members that will contain the high level language structures for the Web service request:
  • For a service provider, the Web service request is the input to the application program
  • For a service requester, the Web service request is the output from the application program
DFHWS2LS generates a partitioned data set member for each operation. It generates the member name by appending a two digit number to the prefix.

Although this parameter is optional, you must specify it if the Web service description contains a definition of a request.

RESPMEM=value
Specifies a 1 - 6 character prefix that DFHWS2LS uses to generate the names of the partitioned data set members that will contain the high level language structures for the Web service response:
  • For a service provider, the Web service response is the output from the application program
  • For a service requester, the Web service response is the input to the application program
DFHWS2LS generates a partitioned data set member for each operation. It generates the member name by appending a two digit number to the prefix.

If there is no response (that is, for one way messages) omit this parameter.

STRUCTURE=(request,response)
For C and C++ only, specifies how the names of the request and response structures are generated.
The generated request and response structures are given names of requestnn and responsenn where nn is a numeric suffix that is generated to distinguish the structures for each operation.

If one or both names is omitted, the structures have the same name as the partitioned data set member names generated from the REQMEM and RESPMEM parameters that you specify.

Start of changeSYNCONRETURN=NO|YESEnd of change
Start of changespecifies whether the remote Web service can issue a syncpoint.
NO
The remote Web service cannot issue a syncpoint. This value is the default. If the remote Web service issues a syncpoint, it fails with an ADPL abend.
YES
The remote Web service can issue a syncpoint. If you select YES, the remote task is committed as a separate unit of work when control returns from the remote Web service. If the remote Web service updates a recoverable resource and a failure occurs after it returns, the update to that resource cannot be backed out.
End of change
Start of changeTRANSACTION=nameEnd of change
Start of changeIn a service provider, this parameter specifies the 1-4 character name of an alias transaction that can start the pipeline. The value of this parameter is used to define the TRANSACTION attribute of the URIMAP resource when it is created automatically using the PIPELINE scan command.
Acceptable characters:
A-Z a-z 0-9 $ @ # _ < >
End of change
URI=value
In a service provider, this parameter specifies the relative URI that a client will use to access the Web service. CICS uses the value specified when it generates a URIMAP resource from the Web service binding file created by DFHWS2LS: the parameter specifies the path component of the URI to which the URIMAP definition applies.
In a service requester, the URI of the target Web service is not specified with this parameter: the URI specified in the Web service description is used, although you can override that with the URI option on the EXEC CICS INVOKE WEBSERVICE command.
Start of changeUSERID=idEnd of change
Start of changeIn a service provider, this parameter specifies a 1-8 character user ID which can be used by any Web client. For an application-generated response or a Web service, the alias transaction is attached under this user ID. The value of this parameter is used to define the USERID attribute of the URIMAP resource when it is created automatically using the PIPELINE scan command.
Acceptable characters:
A-Z a-z 0-9 $ @ #
End of change
WSBIND=value
The fully qualified HFS name of the Web service binding file. DFHWS2LS creates the file (but not the directory structure) if it does not already exist.
WSDL=value
The fully qualified HFS name of the file that contains the Web service description.

Other information

Example

//WS2LS JOB  'accounting information',name,MSGCLASS=A
//  SET QT=''''
//JAVAPROG EXEC DFHWS2LS,
// TMPFILE=&QT.&SYSUID.&QT
//INPUT.SYSUT1 DD *
PDSLIB=//CICSHLQ.SDFHSAMP
REQMEM=CPYBK1
RESPMEM=CPYBK2
LANG=COBOL
Start of changeLOGFILE=/u/exampleapp/wsbind/inquireSingle.logEnd of change
Start of changeMAPPING-LEVEL=1.0End of change
PGMNAME=DFH0XCMN
URI=exampleApp/inquireSingle
PGMINT=COMMAREA
WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind
WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl
/*