Syntax, linkage, and programming considerations

Programming interface files provided by the HTTP enabler

Table 1 lists the programming interface files provided by the z/OS HTTP enabler.

Table 1. HTTP enabler
Programming language	Programming interface file
C / C++	Include file HWTHIC provided in SYS1.SIEAHDRV.H
COBOL	Copybook file HWTHICOB provided in SYS1.MACLIB
PL/I	Include file HWTHIPLI provided in SYS1.MACLIB
Assembler	Include file HWTHIASM provided in SYS1.MACLIB
REXX	See HWTCONST — Initialize predefined variables (REXX) on how to access all the toolkit constants in REXX

Calling formats

Table 2 lists specific calling formats for languages that can invoke the z/OS HTTP enabler callable services.

Table 2. Calling formats for the z/OS HTTP enabler callable services
Programming language	Calling format
C / C++	`HTTPenabler_service_name (return_code,parm1,parm2,…)`
COBOL	`CALL` `HTTPenabler-service-name` `USING` `return_code,parm1,parm2,…`
PL/I	`CALL` `HTTPenabler_service_name (return_code,parm1,parm2,…)`
Assembler	`CALL` `HTTPenabler_service_name (return_code,parm1,parm2,…)`,`VLIST`
REXX	`ADDRESS` `HWTHTTP` `"HTTPenabler_service_name return_code parm1 parm2…"`

Linkage considerations

There are two ways for a compiled application to find the z/OS HTTP enabler callable services:

Linkage stub method
(Recommended) Use the linkable stub routine HWTHCSS from SYS1.CSSLIB to link edits your object code. If you attempt to run the z/OS web enablement toolkit on a previous release of z/OS that does not support the z/OS HTTP enabler, this method results in the service call receiving a return code of X'F06' (HWTH_UNSUPPORTED_RELEASE).
Direct linkage method
Code the linkage to the z/OS HTTP enabler services directly. This can be done if the program first confirms that the level of z/OS contains the toolkit. The following example shows the assembler linkage:
```
L     R14,CVTCSRT-CVT(R14,0)       
L     R14,88(R14,0)                
L     R15,4*HWT_SERV_xxxxx(R14,0)
LR    R14,R0
LR    R0,R13                       
BR    R15                                
```
In the example, xxxxx represents the last five letters of the service you want to call. This requires that the HWTHKASM assembler macro be included. If you attempt to run the HTTP enabler on a previous release of z/OS that does not support the HTTP enabler, this method results in the application receiving an abend X'019'.

Linkage considerations for high-level language programming

Callers must ensure that the proper linkage is made to the HTTP enabler services. The supplied IDF files for the various high-level languages contain the necessary definitions that ensure that the parameter list passed to the HTTP enabler has the high-order bit turned on for the last parameter. For example, for C, the linkage must be specified as OS linkage, such as:

#pragma linkage(HWTHxxxx_CALLTYPE,OS)

For PL/I, the entry declaration should have the following options defined:

OPTIONS(LINKAGE(SYSTEM))

Linkage considerations for assembler language programming

Callers must also use the following linkage conventions:

Register 1 must contain the address of a parameter list that is a list of consecutive words, each containing the address of a parameter to be passed. The last word in this list must have a 1 in the high-order (sign) bit.
Register 13 must contain the address of an 18-word save area.
Register 14 must contain the return address.
Register 15 must contain the entry point address of the service being called.
If the caller is running in AR ASC mode, access registers 1, 13, 14, and 15 must all be set to zero.
On return from the service, general and access registers 2 - 14 are restored (registers 0, 1 and 15 are not restored).

Code page consideration

All input data into the HTTP enabler, except for body data, is assumed to be in EBCDIC encoding (code page 1047) before making any z/OS HTTP enabler service call. The toolkit translates any required data to meet any RFC code page standards when sending or receiving HTTP header data. Data specified in the request body or received in the response body is treated as-is unless the application requests the toolkit to translate from EBCDIC to ASCII or vice versa (see the documentation for HWTH_OPT_TRANSLATE_REQBODY and HWTH_OPT_TRANSLATE_RESPBODY later). Other than these options, the toolkit makes no attempt to translate this data into any format. It is the responsibility of the application to translate the data in either body into the correct encoding.

Environmental considerations

The following environmental considerations apply:

OMVS segment required: The toolkit uses TCP/IP sockets and Cryptographic Services System SSL services. Because both TCP/IP sockets and the SSL services require a z/OS UNIX (POSIX) environment, the HTTP enabler runs with a Language Environment® (LE) POSIX(ON) environment. A POSIX(ON) environment requires the user ID associated with the address space using the HTTP enabler services to have an OMVS segment defined and associated with it. See the appropriate security product documentation, as applicable to your installation, for instructions on how to define an OMVS segment to a user. Failure to properly define the OMVS segment for the user invoking the HTTP enabler will likely result in an HWTH_ENVIRONMENTAL_ERROR return code.

z/OS UNIX limit of processes with a POSIX(ON) environment and its effect on concurrent connections: z/OS UNIX limits the number of concurrent POSIX(ON) environments that can be defined to a single address space. Since each HTTP enabler connection attempts to initialize a new POSIX(ON) environment (because of the environmental requirements listed earlier), each connection gets implicitly dubbed by LE. (Dub means to make a z/OS address space known to z/OS UNIX System Services. Once dubbed, an address space is considered to be a process.) If multiple connections are wanted from the same application (address space), a consideration of the dubbing configuration for the address space in which the HTTP enabler is running may be necessary.

The dubbing behavior that z/OS UNIX takes is customizable by using the z/OS UNIX set dub default service (BPX1SDD or BPX4SDD). If the dub default for the address space is set to DUBPROCESS, this allows concurrent subtasks to each have their own POSIX(ON) environment and, thereby, allow multiple connections from within the same address space, provided that each subtask has at most one connection.

Security considerations

There are several aspects of security to consider at both the connection level and the request level.

Connection security Considerations for connection security include:

TCP/IP stack and security product control: A toolkit application connecting to a server is limited by security profiles and definitions that are already in effect on the system where the application resides. Powerful controls, such as z/OS Communications Server NetAccess, in conjunction with security profiles defined using the SERVAUTH class, can be used to control network access authority, TCP/IP stack access authority, port access authority, and more. These security definitions can be configured to be as granular as required by an installation. See z/OS Communications Server: IP Configuration Guide and z/OS Communications Server: IP Configuration Reference for more information.
SSL/TLS connections: If requested by the application, the toolkit creates an SSL/TLS connection instead of a standard socket connection. These protocols provide data privacy and integrity, including server and client authentication, that is based on public key certificates. The toolkit uses z/OS System SSL services (part of the z/OS Cryptographic Services base component) to facilitate these SSL/TLS connections. (The term SSL is used throughout this publication to describe both the SSL and TLS protocols.) The certificate store configuration required by System SSL must be set up before making an SSL connection. The toolkit supports certificates stored in a key database file, a RACF® key ring, or as a z/OS PKCS #11 token.

Request security: While an HTTP request flows over a secure SSL/TLS connection, the payload of the HTTP request is private between the client and the server. HTTP provides additional protocols to allow a user to authenticate with the server. In many cases, these additional authentication methods flows over an SSL connection exclusively to make sure that the security credentials are flowed from the client to the server in a private manner.

The toolkit implicitly supports basic client authentication, which packages a user ID and password in a format specified by RFC 1945. The HWTH_OPT_HTTPAUTH, HWTH_OPT_USERNAME, and HWTH_OPT_PASSWORD settable options can be used to have the toolkit automatically create the necessary HTTP header.

Additional authentication schemes can be used explicitly by providing the specific HTTP headers and data. Authentication cookies can sometimes be used as a method by web servers to know whether the user is logged in or not, and the account with which they are logged in.

Problem determination considerations

Problem determination in a client/server web services application can be challenging. Here are a few debugging options that can aid in the debugging of your application:

Diagnostic area (diagArea): Each HTTP toolkit API requires the application to specify the diagArea parameter, a diagnostic output area that contains additional information that can be useful when a service fails with a nonzero return code or even in certain cases when the return code is zero. Start of change

The diagArea includes three pieces of information: HWTH_Service, HWTH_ReasonCode, and HWTH_ReasonDesc. End of change

HWTH_Service: A 4-byte constant value that indicates which internal service invoked by the toolkit detected the possible error. To determine which service, consult the first two bytes of this field and locate that value in the defined service constants provided in the IDFs (include files).
Note: The last two bytes are for IBM® and can be provided to IBM Support, if necessary.
HWTH_ReasonCode: A specific error code returned by the internal service identified by HWTH_Service. This can be useful in determining the reason why a particular service failed.
HWTH_ReasonDesc: A 128-character field that contains a more detailed description of the problem. In many cases, this information is sufficient to determine the cause of the problem. In some cases, additional information is also provided here that you can provide to IBM Support if you cannot determine the problem after using the other problem determination techniques described here.

Verbose option: The HTTP enabler provides the option to get more information related to communications and data exchanged between the application and the web server by enabling the HWTH_OPT_VERBOSE option (setting this option to the HWTH_VERBOSE_ON value using the HWTHSET service). Start of change You can also select the destination of these trace messages. If you want to direct these messages to the application's standard output, no further action is necessary. If you want to direct the messages to a particular data set or file, you can use the HWTHSET service to set the HWTH_OPT_VERBOSE_OUTPUT option. (For more information about the HWTH_OPT_VERBOSE_OUTPUT option, see HTTP/HTTPS enabler options and values.) In many cases, these messages can help you quickly determine the root cause of a web application problem. End of change Typically, you would use the verbose option during application debugging, then turn it off when the application is in production.

SOCKAPI interface: z/OS Communication Server provides a SOCKAPI CTRACE option, provided by TCP/IP, which can be used by application programmers to debug problems in their applications. The SOCKAPI option captures trace information that is related to the socket API calls that an application might issue. The SOCKAPI option is intended for use by TCP/IP support and provides information for debugging problems in the TCP/IP socket layer, z/OS UNIX System Services, or the TCP/IP stack. See z/OS Communications Server: IP Diagnosis Guide for more information about this problem determination methodology.

Recovery considerations

The z/OS HTTP enabler runs in the address space of the application. In addition, all the storage needed by the HTTP enabler is obtained in the application’s address space. Because every application has its own programming environment, it is impossible for the HTTP enabler to predict the recovery environment required by the application.

The HTTP enabler provides a simple ESTAE recovery mechanism that provides a minimal recovery scheme for many environments from which the toolkit could be used. Programs that run under an FRR cannot avail themselves of the HTTP enabler recovery. Furthermore, the recovery provided by the HTTP enabler does not catch all errors. Therefore, it is imperative that a robust application provides its own recovery to catch any abnormal ends during toolkit execution.

When the HTTP enabler attempts to access application-provided parameters and those parameters are either inaccessible, point to an inaccessible location, or specify a length that goes beyond the available storage obtained by the application, an abend occurs. In many cases, the recovery of the toolkit catches the error and returns normally to the application with the returnCode parameter set to HWTH_INACCESSIBLE_PARM and the reasonDesc value in the diagArea set to the name of the bad parameter. There are some cases where parameter checking must occur outside of the HTTP enabler recovery environment. In these cases, the returnCode parameter is set to the error return code. If the toolkit abnormally ends, the application’s recovery can consult the returnCode and diagArea values in the callers dynamic storage at the time of the abend and determine which parameter the toolkit could not process.

Note: Language Environment (LE) callers can see an LE-specific abend code other than 0C4. Under certain circumstances, the LE message, CEE3501S The module xxxxxxxx was not found, can appear in standard output, where xxxxxxxx is the application program’s LE condition handler. The calling LE program still receives control with the failing toolkit return code and diagArea information.

Redirection considerations

The HTTP enabler supports automatic redirection (URL/URI forwarding) of requests from one location to another based on the HTTP specifications, as documented in the various RFC publications.

Cross-domain and non-cross-domain redirection: Redirecting a request can be as simple as reissuing an HTTP request to a resource on the same domain but with a different path (non-cross-domain redirection), or can be more involved by establishing a new connection to another domain and then reissuing the HTTP request to that new domain location (cross-domain redirection). The application can choose to allow or disallow cross-domain redirection by using the HWTH_OPT_XDOMAIN_REDIRECTS set option.

Redirection protocol change: A particular HTTP scheme (protocol) can sometimes be requested by a server when it notifies the client of the new redirect location. The application can choose what protocol changes are allowed by using the HWTH_OPT_REDIRECT_PROTOCOLS set option.

Number of redirect attempts: An application can limit the number of redirection that the toolkit is to attempt by setting the HWTH_OPT_MAX_REDIRECTS set option to a value. If no value is specified, the toolkit defaults to a maximum of five attempts.

General redirect behavior—some technical details: There is a number of valid redirect status response codes that can be sent from the server back to the client. The response to these status codes is dictated, usually, by the various RFCs that deal with HTTP redirect processing. The toolkit automatically processes redirects whenever it is safe to do so to unburden the application. The toolkit cannot automatically process an HTTP request that uses an unsafe method to protect the application. Table 3 describes how the toolkit handles each of the HTTP redirection status response codes (3xx), in accordance with current industry standards.

Table 3. Toolkit handling of HTTP redirection status response codes
Received HTTP status response codes	Toolkit behavior
300 Multiple Choices 307 Temporary Redirect	The toolkit attempts to redirect the request to the location specified in the Location response header if and only if the application specifies a HWTH_OPT_REQUESTMETHOD value of HWTH_HTTP_REQUEST_GET, provided the other redirect options set by the application allow the toolkit to redirect the request. For other methods or if the Location header is not specified, the request is not redirected. In this case, the response header callback routine is driven for each response header along with the status response code. The application can choose to issue a subsequent request.
301 Moved Permanently 302 Found 303 See Other	The toolkit automatically redirects the request, provided the other options set by the application allow the toolkit to redirect the request. If the application specifies a HWTH_OPT_REQUESTMETHOD value of HWTH_HTTP_REQUEST_GET, the redirect is identical to the initial request, except to the new target. However, if the HWTH_OPT_REQUESTMETHOD value is anything other than HWTH_HTTP_REQUEST_GET, the toolkit follows the industry de facto client behavior and downgrades the request to HWTH_HTTP_REQUEST_GET. Under no circumstances will an unsafe HWTH_OPT_REQUESTMETHOD value of HWTH_HTTP_REQUEST_POST, HWTH_HTTP_REQUEST_PUT, or HWTH_HTTP_REQUEST_DELETE be forwarded with the request method unchanged.

REXX Programming Considerations

The toolkit provides a REXX host command environment, HWTHTTP, to allow REXX applications to easily direct their requests to the HTTP enabler using an easy-to-use "made-for-REXX" interface. REXX applications running in TSO/E, System REXX, z/OS UNIX, or ISV-provided REXX environments are supported.

To initialize the HWTHTTP host command environment in your REXX exec, it may be necessary to invoke the hwtcalls function at the beginning of your application: call hwtcalls on. After this invocation, both the ADDRESS HWTHTTP and ADDRESS HWTJSON host commands will direct API calls to the toolkit.
To declare all toolkit constants in your REXX exec, use the HWTCONST service as documented below. Note: there is no REXX IDF (include file) provided by the toolkit.
The toolkit services allocate task associated resources, which are released at task termination and the termination API calls.
Handles are not shared among multiple tasks, which can restrict some reentrant REXX environments.
HTTP handles can be updated by any of the HTTP services. The content of these variables should not be modified in any way by the application.
Verify that all variables have proper content and are exposed if set outside of procedures.
Variable names specified on toolkit REXX service calls are limited to 40 characters in length.
REXX does not have unlimited variable content size. In general, a single variable cannot contain more than 16 MB of content. This limits the amount of data that can be sent and received in the HTTP request and response bodies. If the data required is greater than 16 MB for any of these cases, consider to use one of the high-level languages, which are supported by the toolkit (C/C++, COBOL, PL/I or Assembler).
Programs running in any REXX environment that accesses z/OS UNIX from their address space codes CALL SYSCALLS 'SIGOFF' in their REXX exec before invoking any HTTP toolkit service (HWTH* services) to turn off MVS™ signaling. Failure to do this in your REXX exec can result in an HWTH_ENVIRONMENTAL_ERROR(‘F05’X) return code from the service.
The built-in REXX RC variable contains the return code from the REXX HWTHTTP host command. This return code indicates the toolkits acceptance of the supplied REXX HWTHTTP host command. The return codes returned in the RC variable are generally unique to the REXX environment. In contrast, the HTTP service return code, the variable supplied on the service call itself, is only completed if the RC variable has a value of HWTH_OK (0) or HWT_REXXParmSyntaxError(1). Possible return codes returned by the toolkit in the RC variable are:

Host command return codes for the REXX environment: End of change

Table 4. Host return codes for REXX
Host return code	Meaning and action
0	Meaning: REXX toolkit host command successful. Action: Consult the toolkit return code on the service call to determine the final result of the request.
1 HWT_REXXParmSyntaxError	Meaning: REXX toolkit host command detects the parameter format is not in the proper form to be accepted. Action: Check for a probable coding error. See the return code on the toolkit service call to determine the reason for the syntax error. See the REXX programming considerations of the toolkit service to see the exact calling specifications. Compare the toolkit REXX service call attempted with service call examples in the supplied toolkit REXX programming sample found in SYS1.SAMPLIB. See the DiagArea for further diagnostic information.
2 HWT_REXXUnsupportedService	Meaning: Program error. An unknown toolkit service name was specified on the toolkit REXX host command. Action:Check for a probable coding error. Specify a valid toolkit service name. For example, HWTHCONN.
3 HWT_REXXInvalidNumOfParms	Meaning: Program error. The number of parameters specified on the toolkit REXX host command for the service name specified does not match the number of parameters expected. Action:Check for a probable coding error. See the REXX programming considerations of the toolkit service to see the exact calling specifications. Compare the toolkit REXX service call attempted with service call examples in the supplied toolkit REXX programming sample found in SYS1.SAMPLIB.
4 HWT_REXXStemVarRequired	Meaning: Program error. The toolkit REXX service specified on the toolkit REXX host command is missing one or more required stem variables in the positional parameter list. Action:Check for a probable coding error. See the REXX programming considerations of the toolkit service to see the exact calling specifications. A stem variable parameter must specify a "." following the variable name. For example, "var.". Also, compare the toolkit REXX service call attempted with service call examples found in the supplied toolkit REXX programming sample found in SYS1.SAMPLIB.
5 HWT_REXXParmNameTooLong	Meaning: Program error. One or more variables specified on the toolkit REXX service call on the toolkit REXX host command is greater than the toolkit maximum REXX variable length (40). Action: Check for a probable coding error. Reduce the variable name lengths on the toolkit REXX service call to be 40 characters or less in length
6 HWT_REXXInvalidHostEnv	Meaning: System error. The toolkit detected an unexpected error. The system rejects the service call. Action: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.
32 HWT_REXXUnexpectedError	Meaning: System error. An unexpected error is detected. The system rejects the service call. Action: A symptom record has been written to LOGREC to record the problem. Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.

Using the REXX APIs in a z/OS UNIX Environment

Programs running in any REXX environment that accesses z/OS UNIX from their address space must turn off MVS signaling by coding CALL SYSCALLS "SIGOFF" in the REXX exec before invoking any HTTP toolkit service (HWTH* services). Failure to do this in your REXX exec can result in an HWTH_ENVIRONMENTAL_ERROR(‘F05’X) return code from the service.

z/OS HTTP enabler programming examples

The z/OS HTTP enabler provides a sample program in all supported programming languages to aid in the creation of applications that use the toolkit functions. Each sample contains examples of how to use almost all of the HTTP enabler services available in the toolkit. The samples are shipped in SYS1.SAMPLIB. Table 5 lists the sample files for each programming language.

Table 5. z/OS HTTP enabler programming sample files
Programming language	Name of sample in SYS1.SAMPLIB
C / C++	HWTHXC1
COBOL	HWTHXCB1
PL / I	HWTHXPI1
REXX	HWTHXRX1