Management of REST service client information

Db2 DDF implicitly defines special registers and a global variable to store client information about a valid HTTP REST service request. The client information is externalized in accounting records and the output of the -DISPLAY command.

Db2 allows a subset of characters from the first 128 Unicode code points to be stored as client information. See the Allowable characters for client information section for a complete list of allowable characters. When processing a REST service request, Db2 stores the client information in the following special registers:

CURRENT CLIENT_ACCTNG

Contains the value of the client accounting string. The Db2 REST services maximum supported length of the CURRENT CLIENT_ACCTNG value is 255 characters.

A user specified value can be set using the HTTP request header field Db2-Client-Acctng.

The Db2 generated default value contains the string of an HTTP REST GET or POST method that is concatenated with the name of a qualified service in the form of <collectionID.serviceName>, as in GET SYSIBMSERVICE.simpleSelect1 or POST SYSIBMSERVICE.simpleSelect1. <serviceName> might be truncated.

CURRENT CLIENT_APPLNAME

The Db2 REST services maximum supported length of the CURRENT CLIENT_APPLNAME value is 128 characters.

A user specified value can be set using the HTTP request header field Db2-Client-ApplName.

The Db2 REST generated default value is the service name string in the service request.

CURRENT CLIENT_CORR_TOKEN

The Db2 REST services maximum supported length of the CURRENT CLIENT_CORR_TOKEN is 128 characters.

A user specified value can be set using the HTTP request header field X-Correlation-ID or the HTTP request header field Db2-Client-Corr-Token. If both HTTP X-Correlation-ID and Db2-Client-Corr-Token request header fields are present in the request, then the Db2-Client-Corr-Token field value is used.

The Db2 REST generated default value is the logical unit of work identifier or LUWID string that is generated for the thread without the commit count for the service request. The correlation token can be used to correlate any downstream connections that are used by the service.

CURRENT CLIENT_USERID

The Db2 REST services maximum supported length of the CURRENT CLIENT_USERID is 128 characters.

A user specified value can be set using the HTTP request header field Db2-Client-Userid.

The Db2 REST generated default value is the authentication ID string. The authorization ID is used to establish an HTTP connection for the service request.

CURRENT CLIENT_WRKSTNNAME

The Db2 REST services maximum supported length of the CURRENT CLIENT_WRKSTNNAME is 255 characters.

A user specified value can be set using the HTTP request header field User-Agent or Db2-Client-WrkStnName. If both User-Agent or Db2-Client-WrkStnName request header fields are present in the request, then the Db2-Client-WrkStnName is used. Many REST clients set the User-Agent header value to a default string that represents the name and version of the REST client that is being used.

The Db2 REST generated default value is the client IP address string. The IP address is associated with the client that sent the REST service request.

Db2 also stores information about the HTTP REST service request in the following built-in global variable:

SYSIBM.CLIENT_IPADDR
Contains the value of the client IP address string.

The IP address is associated with the client that sent the REST service request.

Allowable characters for client information values

All Db2 HTTP request header client information values must be provided in UTF-8 encoding and consist only of a subset of characters from the first 128 Unicode code points. Specifically, only the following single byte Unicode characters are allowed in Db2 REST services client information values:
Description Character Unicode code point
Upper Case Alpha A-Z X'41'-X'5A'
Lower Case Alpha a-z X'61'-X'7A'
Numeric 0-9 X'30'-X'39'
Blank (sp) X'20'
Number Sign/Pound Sign # X'23'
Dollar Sign $ X'24'
Percent Sign % X'25'
Ampersand & X'26'
Left Parenthesis ( X'28'
Right Parenthesis ) X'29'
Asterisk * X'2A'
Plus Sign + X'2B'
Comma , X'2C'
Hyphen/Minus - X'2D'
Period . X'2E'
Slash/Solidus / X'2F'
Colon : X'3A'
Semi-Colon ; X'3B'
Less Than Sign < X'3C'
Equal = X'3D'
Greater Than Sign > X'3E'
At Sign @ X'40'
Underscore _ X'5F'
     
Any disallowed Unicode character code points found in the input client information values will be replaced by the period (x'2E') character. Although Db2 REST services client information values allow the use of several variant characters, such as #, @, $, and others, it is suggested that users use only the invariant characters when possible. This suggestion is to avoid any unexpected display issues of the client information values after translation to the Db2 system EBCDIC CCSID. The Db2 client information values may be included in various Db2 console messages, trace records, and other external representations, which might not display as expected if variant characters are used in the client information settings.