Generation

The important instructions for communicating with HTTP clients are:

• BCAMAPPL
• TPOOL
• HTTP-DESCRIPTOR
• CHAR-SET (BS2000-Systeme)

BCAMAPPL

You can use a BCAMAPPL statement to generate a transport system end point for HTTP clients in the UTM application.

BCAMAPPL <bcamname>

,LISTENER-PORT = number
,SIGNON-TAC    = *NONE
,T-PROT        = (SOCKET, *HTTP | *ANY, [SECURE])
[,USER-AUTH    = *NONE | *BASIC]

In the LISTENER-PORT parameter, you specify the port number that HTTP clients must use to address the UTM application.

A BCAMAPPL statement intended for access by HTTP clients must be generated without a logon procedure, that is, *NONE must explicitly be specified for the SIGNON-TAC parameter.

In the parameter T-PROT you must specifiy *HTTP or *ANY as a variant of the socket protocol. By specifying SECURE, you can define that communication has to take place via SSL connections.

The USER-AUTH parameter can be used to specify that a user must log on to the UTM application with his or her UserID and password.

TPOOL

In order for an HTTP client to be able to connect to the UTM application, a logical connection point called a LTERM partner must be generated. You can use a TPOOL statement to generate a pool of LTERM partners for HTTP clients. The TPOOL must be generated with PTYPE=SOCKET, MAP=USER and USP-HDR=NO.

TPOOL BCAMAPPL  = <bcamname>

,LTERM   = <prefix>
,MAP     = USER
,NUMBER  = number
,PRONAM  = *ANY | <subnet>
,PTYPE   = SOCKET
,USP-HDR = NO
,ENCRYPTION-LEVEL = <level>

If the BCAMAPPL is generated with T-PROT=(Socket,...,SECURE) then the value for ENCRYPTION-LEVEL is implicitly set to TRUSTED, that is, HTTP clients that connect via this TPOOL are considered trustworthy.

HTTP-DESCRIPTOR

The HTTP-DESCRIPTOR statement can be used to map the path specification of an HTTP request to a TAC of the UTM application.

HTTP-DESCRIPTOR <http-descriptor-name>
      [,BCAMAPPL     = <bcamappl> | *ALL]
      [,CONVERT-TEXT = *YES | *NO]
      [,HTTP-EXIT    = <program-name> | *NONE | *SYSTEM ]
       ,PATH          = C'<path1..254>'
       ,TAC           = <tac>
      [,USER-AUTH    = *NONE | *BASIC]

The parameter BCAMAPPL can be used to determine whether the assignment of path to TAC should only be valid for HTTP requests that arrive via a particular transport system end point, or whether they should be valid for all HTTP connections regardless of the transport system end point.

In BS2000 systems, the parameter CONVERT-TEXT can be used to specify whether or not openUTM is to perform a code conversion of the query and the message body of an HTTP request.

In the HTTP-EXIT parameter, the user can specify a program that formats HTTP messages for an existing program unit. openUTM then calls this program for incoming and outgoing HTTP messages. With *SYSTEM, you can specify that openUTM should convert output messages to HTML format.

In the PATH parameter, you define the path that is to be assigned to the TAC specified in the TAC parameter. The path specification may contain a "*" as the last character, which is then evaluated as a wildcard character. This makes it easy to assign path specifications that are identical in their leading part to the same TAC.

In the USER-AUTH parameter, you can specify whether HTTP requests that are assigned to this HTTP descriptor must contain authentication data. If the value *BASIC is specified here, the client must provide information about the UserId and password in the authorization header of an HTTP request. If this is not the case, then openUTM requests this information by sending of a response with status code "401 Unauthorized".

CHAR-SET (BS2000 systems)

The protocol segments of an HTTP message (incl. query) are always encoded in US ASCII and are converted to EBCDIC by openUTM in BS2000. The user message can be encoded in different ways. This means that, at least in BS2000 systems, segments of an HTTP message must be encoded according to EBCDIC.

In BS2000 systems, the generation statement CHAR-SET can be used to assign Character Set names to the code conversion tables SYS1, ..., SYS4 of openUTM.

CHAR-SET { SYS1 | SYS2 | SYS3 | SYS4 }

             ,NAME = (C'<char-set-name1..32>', ...)

If CONVERT-TEXT=*YES is generated for an HTTP DESCRIPTOR in BS2000 systems, openUTM analyzes the content-type header for HTTP requests that can be assigned to this HTTP descriptor. If a character set defined in openUTM with a CHAR-SET statement is found, openUTM performs a code conversion for the message body of the HTTP request with the conversion table assigned by the CHAR-SET statement. openUTM then also uses the corresponding conversion table for the the message body of the HTTP response.