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.
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.

>>-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
- You can specify the input parameters in any order.
- Each parameter must start on a new line.
A parameter (and its continuation character, if you use
one) must not extend beyond column 72; columns 73 to 80 should contain
blanks.
- If a parameter is too long to fit on a single line, use an asterisk
(*) character at the end of the line to indicate that the parameter
continues on the next line. Everything (including spaces) before the
asterisk is considered part of the parameter. For example:
WSBIND=wsbinddir*
/app1
is equivalent toWSBIND=wsbinddir/app1
- A # character in the first character position of the line is a
comment character. The line is ignored.
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.
CCSID=value
Specifies 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.

- 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.
CHAR-VARYING-LIMIT=32767|value
Specifies 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.

- 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.
The 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.
DEFAULT-CHAR-MAXLENGTH=255|value
Specifies 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.

- 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.
HTTPPROXY-USERNAME=value
Specifies 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.
HTTPPROXY-PASSWORD=value
Specifies 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.
- 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.
LANG=PLI-OTHER
Specifies that the programming language of the high level language
structure is a level of PL/I other than Enterprise PL/I.
- 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.
MAPPING-LEVEL={1.0|1.1|1.2}
Specifies 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.
MINIMUM-RUNTIME-LEVEL={MINIMUM|1.0|1.1|1.2|CURRENT}
Specifies 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.

- 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.
PDSCP=value
Specifies 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.
- 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.
When
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.
- 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.
SYNCONRETURN=NO|YES
specifies 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.

TRANSACTION=name
In 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 $ @ # _ < >
|

- 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.
USERID=id
In 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 $ @ #
|

- 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
- The user ID under which DFHWS2LS runs must be defined to OMVS.
The user ID must have read permission to the CICS HFS
file structure and PDS libraries, and write permission to the directories
specified on the LOGFILE, WSBIND,
and WSDL parameters.
- The user ID must have a sufficiently large storage allocation
to run Java.
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
LOGFILE=/u/exampleapp/wsbind/inquireSingle.log
MAPPING-LEVEL=1.0
PGMNAME=DFH0XCMN
URI=exampleApp/inquireSingle
PGMINT=COMMAREA
WSBIND=/u/exampleapp/wsbind/inquireSingle.wsbind
WSDL=/u/exampleapp/wsdl/inquireSingle.wsdl
/*