imtkmake command

Enables you to create and deploy a COBOL program-based service interface, and generate a client application to access the service.

Syntax:

imtkmake -defmap          service=service-name
                          src=program-name
                          type=service-type
                         [directives=Compiler-directives] 
                         [entrypoint=entry-point-name]
                         [method={POST|GET|PUT|DELETE}]
                         [path=operation-path]
                         [settings=properties-filename]
                         [transactionAttribute=attribute]

imtkmake -generate        service=service-name
                          type=service-type
                         [allowcredentials={yes|no}]
                         [allowedorigin=uri]
                         [appdir=directory-name]
                         [appserver=J2EE-application-server-name]
                         [archivename=arch-name]
                         [basePath=base-path]
                         [bean=bean-name]
                         [classpath=pathname]
                         [ejbInterfaceType={remote|local}]
                         [ejbname=ejb-name]
                         [ejbversion=3]
                         [esruntime=esruntime-filename]
                         [exithandler=program-name]
                         [exposedheaders=header[,header[…]]]
                         [filename]...
                         [@filelistname]
                         [j2eeVersion={1.7|7}]
                         [jarname=jar-filename]
                         [javacpath=java-dir]
                         [namespace=service-namespace] 
                         [package=package-name]
                         [sepsession={stateless|stateful}]
                         [serverHost=host-name]
                         [serverPort=port-number]  
                         [session={stateless|stateful}] 
                         [settings=properties-filename]
                         [style={doclit|rpcenc}]
                         [transaction={application|container}]
                         [transactional={yes|no}]
                         [url=ip-address]
                         [version=version]

imtkmake -query          [username=secure-username]
                         [password=secure-password]

imtkmake -queryAppServerList

imtkmake -queryEJBDefaults

imtkmake -deploy          type=service-type
                         [carname=car-filename]
                         [ejbversion=3]
                         [password=secure-password]
                         [server=server-name,deployer-name]
                         [settings=properties-filename]
                         [username=secure-username]

imtkmake -showlog         deploydir=deployment-directory
                         [username=secure-username]
                         [password=secure-password]

imtkmake -genclient       service=service-name
                          type=service-type     
                         [appserver=J2EE-application-server-name]
                         [basePath=base-path]
                         [classpath=java-class-path]
                         [clientdir=directory-name]
                         [j2eeVersion={1.7|7}]
                         [namespace=service-namespace]
                         [serverHost=host-name]
                         [serverPort=port-number]
                         [style={doclit|rpcenc}]
                         [transactional={yes|no}]
                         [url=ip-address]
                         [version=version]

imtkmake -genclientwsdl   clientwsdl=wsdl-filename
                         [bitmode={32|64}]
                         [charset={asci|ebcdic}]
                         [clientdir=directory-name]
                         [defaultstringsize=string-size]
                         [defaultarraysize=array-size]

imtkmake -genclientjson   clientjson=json/yaml-filename
                         [bitmode={32|64}]
                         [charset={asci|ebcdic}]
                         [clientdir=directory-name]
                         [defaultstringsize=string-size]
                         [defaultarraysize=array-size]
                         [inlineoccurslimit=limit-size]
                         [operations=index[,index[…]]]

imtkmake -validate

imtkmake -help

Parameters:

-defmap

Create a service interface using default mappings based on the COBOL program specified in the src= parameter.

-generate

Generate deployment files based on the parameters set, and generate a COBOL archive (.car) file containing the generated files for deployment to the enterprise server.

-query

List the enterprise servers available for deployment.

-queryAppServerList

List the available J2EE 1.7 application servers by default. Specify the j2eeversion parameter to see application servers supported for other J2EE versions.

-queryEJBDefaults

Lists all the default EJB generation options.

-deploy

Deploy the .car file created with -generate parameter to the enterprise server. Execute imtkmake with the -deploy parameter from the servicename.deploy directory.

-showlog

Display the contents of the deployment log (deploylog.txt file).

-genclient

Generate a client from the service interface, according to the specified type, such as EJB or Web Services.

-genclientwsdl

Generate a COBOL client from WSDL.

-genclientjson

Generate a COBOL client from JSON or YAML Schema or OpenAPI (Swagger).

-validate

Validate the service interface.

-help

Display information about imtkmake functions and parameters.

allowcredentials={yes|no}

Specifies whether or not a response can be exposed when user credentials are included in the request.

allowedorigin=uri

URI allowed to access the returned resource.

archivename=arch-name

The full filename of the output archive file, which can be a .jar, .war, or .ear file.

appdir=directory-name

The path to the application files for the application running on the enterprise server.

appserver=J2EE-application-server-name

This is the name and version of the J2EE application server for which an EJB is generated and to which an EJB is deployed. This defines the deployment descriptors that are generated.

This is mandatory when generating EJBs and EJB clients. In other words, mandatory when using the -generate or -genclient functions with type set to EJB. The values must be within quotes since they contain spaces. For example:

"JBoss EAP 7.2"
"WebSphere 9.0"

Note that this parameter must come after the other parameters.

See -queryAppServerList for how to list the available servers.

basePath=base-path

For REST services, the base path used in the URI of the service.

bean=bean-name

For EJB generation, the name of the bean to generate. Defaults to service-name.

bitmode={32|64}

The bit mode of the generated client.

carname=car-filename

The path to and name of the .car file to deploy. By default, this file is named servicename.car and is in the servicename.deploy directory. carname= is not required when you generate and deploy on the same command line.

charset={asci|ebcdic}

The character set of the generated client.

classpath=java-class-path

The full path to the J2EE implementation classes on the J2EE application server, which is different for each J2EE application server and is the path to the following .jar files respectively:

JBoss jboss-ejb-api*.jar, jboss-connector-api*.jar, and jboss-servlet-api*.jar
Note: The names of these files might vary depending on the version of JBoss you are using.
Tomcat servlet-api.jar
WebSphere j2ee.jar
WebLogic weblogic.jar

Notes:

java-class-path is case sensitive.
The CLASSPATH property points application servers to their required J2EE implementation class files. For a list of application servers and their required J2EE implementation class files, see Application Server J2EE Implementation Classes.

clientdir=directory-name

The directory in which to generate the client program. With the -genclientwsdl or -genclientjson function, defaults to the WSDL or JSON/YAML Schema or OpenAPI (Swagger) file directory; otherwise defaults to the servicename.deploy directory.

clientjson=json-filename

For REST services, the name of the JSON or YAML Schema or OpenAPI (Swagger) file from which to generate the client program.

clientwsdl=wsdl-filename

The name of the WSDL file from which to generate the client program.

defaultarraysize=array-size

The default array size to use for unbounded arrays.

defaultstringsize=string-size

The default string size to use for unbounded strings.

deploydir=deployment-address

The URL of the deploylog.txt file. This URL is displayed by the -deploy function.

directives=Compiler-directives

The directives required for the program to compile correctly. Use a comma between directives.

ejbInterfaceType={remote|local}

The type of server on which the EJB runs - local or remote.

ejbname=ejb-name

For EJB generation, the name of the EJB to generate. Defaults to service-nameEJB.

ejbversion=3

Enable EJB version 3 support.

entrypoint=entry-point-name

The name of the entry point to use for default mapping.

esruntime=esruntime-filename

The name of a file containing the run-time configuration settings to be applied when the deployed service is run. The file extension must be .rtc.

exithandler=program-name

For Web Services generation, the name of a user exit program to handle the exit points in the MFRHSOAP request handler.

exposedheaders=header [,header[…]]

Custom headers that the browser is allowed to access.

@filelistname

The name of a file containing a list of additional files that need to be included in a .car file. Each file name must be on a new line.

filename

An additional file that needs to be included in a .car file. You can specify multiple additional files.

inlineoccurslimit=limit-size

A numerical value representing the minimum minimum array size at which Visual COBOL generates separate data structures for dynamic allocation. For a full explanation on how Visual COBOL generates variable arrays, see Handling Variable Arrays in WSDL and JSON.

j2eeVersion={1.7|7}

The J2EE version. Paired options inside brackets ({}) are equivalent.

jarname=jar-filename

For EJB generation, the name of the .jar file to create. Defaults to service-name.jar.

javacpath=java-dir

The path to the javac.exe file.

method={POST|GET|PUT|DELETE}

For default mapping of REST services, the HTTP method for the created operation(s).

namespace=service-namespace

For Web Services generation, EJB generation and client generation, the service namespace. Web Services generation and client generation defaults to http://tempuri.org/service-name. EJB generation defaults to service-name.

operations=index[,index[…]]

One numerical value or a list of comma-delimited numerical values, where the number represents a 1-based index for an operation contained in the WSDL or JSON/YAML file. The index number is assigned according to the order in which the operations are defined in the file. The default is 1, or the first defined operation.

package=package-name

For EJB generation, the name of the package of Java classes to contain the bean. This is case-sensitive. Defaults to com.mypackage.service-name.

password=secure-password

The password that enables communication with a secure server. This is required only when MFDS is configured to require it.

path=operation-path

For default mapping of REST services, the path for the created operation. Applies only when a single entry point is present or specified.

sepsession={stateless|stateful}

The setting for the associated SEP (Service Execution Process) attribute. SEP attributes are only meaningful when transactional=yes.

server=server-name,deployer-name

The destination of the deployment files. server-name is the enterprise server to which you want to deploy the service, and deployer-name is the name of a deployment service on that enterprise server. If you do not supply this parameter, the function lists the servers available for deployment and prompts you to choose one.

serverHost=host-name

For J2SE Java bean services, the name of the host machine that is running the enterprise server.

serverPort=port-number

For J2SE Java bean services, the port number of the enterprise server listener.

service=service-name

The name of the service for mapping or generation.

session={stateless|stateful}

For EJB generation, the type of EJB to generate. Defaults to stateless.

settings=properties-filename

The name of a file containing the set properties for this service interface.

src=program-name

The program used for creating default mappings.

style={doclit | rpcenc}

The style to use for WSDL generation. The default is doclit.

transaction={application|container}

Specifies whether the service is application-managed or transaction-managed. The default is application.

transactional={yes|no}

For EJB generation, whether or not the EJB service executes in a transactional context. When set to yes, session=stateful by default.

transactionAttribute=attribute

Transaction attribute used for EJB default mapping. Can be one of the following:

notSupported
mandatory
never
required
requiresNew

type=service-type

The type of mapping to perform or type of client to generate (see defmap, genclient and generate above), where service-type can be one of the following:

EJB
J2SEbean
WebService
REST

url=ip-address

For Web Services and client generation, the IP address of the service.

username=secure-username

The user name that enables communication with a secure server. This is required only when MFDS is configured to require it.

version=version

For REST services, the service version used in the URI of the service.

Comments:

Execute imtkmake from a Visual COBOL command prompt in the directory that contains your COBOL program file.
This command performs several functions. You must execute the following against the same program in this order:
- -defmap
- -generate
- -query (optional)
- -deploy
- -showlog (optional)
- -genclient and/or -genwsdl (optional)
You can combine some functions on the same command line:
- -defmap and -generate together, to create a service interface with default mappings and generate deployment files to be deployed at a later time.
- -generate and -deploy together, to generate deployment files for an existing service interface, deploy them to an enterprise server.
- -defmap, -generate, and -deploy together to perform all three functions.
Note: When you combine two or more functions on the same command line, you do not need to repeat parameters that are common.
You can combine the use of the command line functions with the use of the Service Interfaces feature. For example, you might create the service interface and customize it. You could then use the command line to deploy the service interface.
You can create a mapping properties XML file that contains a list of the optional parameters associated with the -generate function, and then specify that file on the command line as a parameter for the -generate function. If you specify any of the same parameters on the command line itself, these override the values set for them in the mapping properties XML file.
You can use () as delimiters around parameters rather than = before them, for example, src(book.cbl) instead of src=book.cbl.
When you deploy a service interface using imtkmake -deploy, imtkmake uses the first instance of each deployable item found, in this order:
- MFDS. If the deployment items are in MFDS, any configuration settings in the [destination] section are used. For example:
```
[destination]
   server=ESDEMO
   listener=Web Services and J2EE
```
- MFDS. If the deployment items are in MFDS, but there aren't any configuration settings, imtkmake uses the enterprise server that owns the service.

Examples:

The following command creates a service interface with default mapping for the program book.cbl:

imtkmake -defmap src=book.cbl service=wmapserv 
                 type=webservice

The following command generates a Web service for the wmapserv service interface:

imtkmake -generate service=wmapserv
                   type=webservice
                   exithandler=myhandler
                   namespace=http://corpuri.org/wmapserv

The following command generates an EJB for the JMapServ service interface:

imtkmake -generate service=JMapServ
                   type=ejb
                   bean=JMap
                   classpath=/usr/java131/lib/j2ee.jar
                   ejbname=JMapEJB
                   esruntime=jmapconf.rtc
                   jarname=JMap.jar
                   package=com.corp.jmap
                   session=stateful                          
                   appserver="WebSphere 9.0"

The following command generates a Web service for the wmapserv service interface and deploys it to the enterprise server ESDEMO. The additional data file data-files-path\bookfile.dat (Windows) or data-files-path/bookfile.dat (UNIX) is deployed:

On Windows platforms:

imtkmake -generate service=wmapserv type=webservice
         -deploy server=ESDEMO,Deployer data-files-path\bookfile.dat

On UNIX platforms:

imtkmake -generate service=wmapserv type=webservice
         -deploy server=ESDEMO,Deployer data-files-path/bookfile.dat

The following command deploys a Web service that has already been generated in wmapserv.car to the enterprise server ESDEMO:

imtkmake -deploy carname=wmapserv.car 
                 server=ESDEMO,Deployer

This submit is a successful deployment, as indicated by the 202 return code, and the presence of the URL in the response message.

The following command displays the deploylog.txt file from the URL http://10.120.72.229:47704/uploads/cw_diYLq:

imtkmake -showlog deploydir=http://10.120.72.229:47704/uploads/cw_diYLq

The following command creates a COBOL client program for the service wmapserv:

imtkmake -genclient type=webservice 
                    service=wmapserv

The following command creates a COBOL client program for the REST service service1 using the base path /servicesApp/ and version 1.0:

imtkmake -genclient service=service1 type=rest 
                    url=http://localhost:9003 
                    basePath=/servicesApp/ 
                    version=1.0

The following command creates a COBOL client program for the service wmapserv using the service's WSDL file:

On Windows platforms:

imtkmake -genclientwsdl clientwsdl=wmapserv.wsdl

On UNIX platforms:

imtkmake -genclientwsdl clientwsdl=$PWD/wmapserv.wsdl 
                        clientdir=$PWD

The following command creates an EJB service interface with default mapping using the requiresNew transaction attribute:

imtkmake -defmap type=ejb 
                 src=calculator.cbl 
                 service=service13.xml 
                 transactionAttribute=requiresNew

The following command generates the required files for the REST service service1 using the base path /servicesApp/ and version 1.0:

imtkmake -generate type=rest
                   url=http://localhost:9003 
                   basePath=/servicesApp/ 
                   version=1.0
                   service=service1

The following command creates a COBOL client program for the wmapserv service using its JSON or YAML Schema file:

imtkmake -genclientjson clientjson=wmapserv.json