IBM Power Systems software > IBM i > Software >

HTTP Server for i

Secure, powerful, and complete

Overview

Getting Started

Documentation

Support

NLS issues with the server APIs (Original)

This page lists information about the Server APIs and the NLS considerations when using them. This is a "MUST READ" for anyone writing applications using these API's.

Contents

Introduction
Server API documentation

Introduction

The purpose of this paper is to document the National Language Support (NLS) considerations for the Server API's. The current implementation is somewhat inconsistent and non-intuitive, so this documentation should be read carefully to fully understand all the implications when using these API's.

Some early PTFs in V4R3 were provided to assist in migrating CGI applications to Server API. These PTF's made the server API's for the "Service" step function the same way that CGI functions with respect to the "CGI mode". "CGI mode" was enhanced in V4R4 by adding an "output CGI mode". There were also some PTF's for this early in V4R4. Therefore, PTF currency is necessary to ensure availability of the coding interfaces documented here. Where conflicts arise, this document should be considered the master over the Web Programming Guide. The Web Programming Guide is not completely correct where it documents the Server API predefined functions in Chapter 7.

This table summarizes the type of conversion that is performed by the server in the Server API Service step for each CGI input mode. Note that there are some exceptions, so you should refer to the additional documentation on HTTPD_extract and HTTPD_read below for these exceptions.

CGI_MODE	Conversion	Stdin encoding	Environment variables	Query_String encoding
%%BINARY%%	None	No conversion	EBCDIC CCSID 37	No conversion
%%EBCDIC%%	NetCCSID to FsCCSID	FsCCSID	EBCDIC CCSID 37	FsCCSID
%%EBCDIC%% - with charset tag received	Calculate target EBCDIC CCSID based on received ASCII charset tag	EBCDIC equivalent of received charset	EBCDIC CCSID 37	FsCCSID
%%EBCDIC_JCD%%	Detect input based on received data. Convert data to FsCCSID	FsCCSID	EBCDIC CCSID 37	Detect ASCII input based on received data. Convert data to FsCCSID
%%MIXED%% (Compatability mode)	NetCCSID to FsCCSID (receive charset tag is ignored)	FsCCSID with ASCII escape sequences	EBCDIC CCSID 37	EBCDIC CCSID 37 with ASCII escape sequences

This table summarizes the type of conversion that is performed by the server in the Server API Service step on output. Note that there are some exceptions, so you should refer to the additional documentation on HTTPD_set, and HTTPD_write below for these exceptions.

CCSID/Charset in HTTP content-type header	Conversion action	Server reply charset tag
EBCDIC CCSID/Charset	Calculate EBCDIC to ASCII conversion based on supplied EBCDIC CCSID/Charset	Calculated ASCII charset
ASCII CCSID/Charset	No conversion	ASCII CCSID/Charset provided
65535	No conversion	None
None (%%BINARY%% or %%BINARY/MIXED%% or %%BINARY/EBCDIC%%)	Default Conversion - FsCCSID to NetCCSID	NetCCSID as charset
None (%%BINARY/BINARY%%)	No conversion	None
None (%%EBCDIC%% or %%EBCDIC/MIXED%% or %%EBCDIC/EBCDIC%%)	Default Conversion - FsCCSID to NetCCSID	NetCCSID as charset
None (%%EBCDIC%% or %%EBCDIC/MIXED%% or %%EBCDIC/EBCDIC%% with charset tag received on HTTP request)	Use inverse of conversion calculated for stdin	Charset as received on HTTP request
None %%EBCDIC_JCD%% or %%EBCDIC_JCD/MIXED%% or %%EBCDIC_JCD/EBCDIC%%	Default Conversion - FsCCSID to NetCCSID	NetCCSID as charset
None (%%MIXED%% or %%MIXED/MIXED%%)	Default Conversion - FsCCSID to NetCCSID	None (compatibility mode)
Invalid	CGI error 500 generated by server

Server API documentation

Here you will find documentation on how to use the server's predefined functions from your server API program. There are no NLS considerations when your Server API program is called by the server. However many of the server's predefined functions do have parameters that need some NLS statements.

HTTPD_authenticate()

There are no changes for this function.

HTTPD_attributes()

This function extracts the attributes of a file and is valid in all steps. The attributes returned include:

Content-Type: xxxx/yyyy;charset=zzzz
Content-Encoding: xxxx
Content-Language: xxxx

The file name parameter is expected to be in EBCDIC codepage 37. The returned attributes are also in EBCDIC codepage 37.

HTTPD_extract()

This function is used to extract the value of a variable associated with the request, ie. an environment variable to CGI. The name parameter is always expected to be in EBCDIC codepage 37.

If you extract "All-Variables" or you extract "Query-String" in the Service step with the CGI mode set to %%EBCDIC%%, %%EBCDIC_JCD%%, or %%BINARY%%, then the value is returned in the EBCDIC default job codepage (the DefaultFsCCSID).

Otherwise, the value is returned in EBCDIC codepage 37.

If you are extracting user variables that you set previously, then you get out what you put in, the server does not perform any translation.

HTTPD_reverse_translate()

This function is used to translate a file system path to a URL. The name is expected to be in EBCDIC codepage 37 and the value is returned in EBCDIC codepage 37.

HTTPD_translate()

This function is used to translate a URL to a file system path. The name is expected to be in EBCDIC codepage 37, and the url_value, path_trans, and query_string are returned in EBCDIC codepage 37.

HTTPD_set()

This function is used to set the value of a variable associated with the request, ie. an enviroment variable to CGI or an HTTP header to be sent in the response. If you are not in the Service step, then the name and the value are expected to be in EBCDIC codepage 37.

If you are in the Service step, it gets more complicated. If you set any HTTP header variable and prefix the name with "HTTP_" then the CGI output mode determines the codepage.

If the CGI output mode is %%MIXED%% or %%EBCDIC%%, then the name and value are expected to be in EBCDIC codepage 37. The only difference between %%MIXED%% and %%EBCDIC%% is the encoded characters (or escaped characters). For %%EBCDIC%%, the encoded characters are of the form %xx where the xx is the EBCDIC codepage 37 representation of the EBCDIC codepage 37 character. For %%MIXED%%, the encoded characters are of the form %yy where the yy is the EBCDIC codepage 37 representation of the ASCII codepage 819 character. What???? Let's take an example. This really only applies to the "Location" header which contains a URL. If you want the Location header to contain a + in the form data, then in %%EBCDIC%% mode, this should be %4E in EBCDIC codepage 37, and for %%MIXED%% mode, it should be %2B in EBCDIC codepage 37. Why??? That's a long story, but in %%MIXED%% mode, the server just does a blind conversion from EBCDIC 37 to ASCII 819 which is the easiest for the server, but it is unnatural for the application dealing with EBCDIC. %%EBCDIC%% allows the application to handle things more naturally and the server gets to handle the unnatural conversion.

If the CGI output mode is %%BINARY%%, the name and value are expected to be in ASCII codepage 819.

If you are in the Service step and set any variable or header without prefixing it with "HTTP_", then both the name and value are expected in EBCDIC codepage 37 if the server is to process it in any way. If you set user variables for whatever purpose and extract them later, then what you put in is what you get out, the server performs no translation unless it is writing headers to send back to the browser. If you use set to alter variables provided in the request, then the name and value are expected in EBCDIC codepage 37 (this includes Query-String).

HTTPD_file()

This function is used to send a file to satisfy a request. The name of the file to send is expected to be in EBCDIC codepage 37.

HTTPD_exec()

This function is used to run a CGI program to satisfy the request. The name parameter is expected to be in EBCDIC codepage 37 and it must be in the form of /QSYS.LIB/lib.LIB/xxx.yyy where lib is the library name where the program is located, xxx is the program name, and yyy is the proper extension (.PGM, .REXX, or .CLASS).

HTTPD_read()

This function is used to read the stdin for the request body. When called in the Service step, it honors the CGI mode.

When called from other steps, it always works in %%MIXED%% mode.

You can also use HTTPD_set to set variable CONVERT_REQUEST_BODY to a value of NO (this defaults to AUTO which means the server tries to determine if conversion is necessary using the content-type and content-encoding headers) prior to your first call to HTTPD_read, to cause the server to do no conversion on the data returned in the buffer.

HTTPD_write()

This function is used to write the body of the response. You should use the HTTPD_set() to set the content-type and possibly the content-encoding to the appropriate values so the server makes the correct conversion decisions. When called in the Service step, it honors the CGI mode and CGI output mode to determine conversions.

When called from other steps, it always works as if in CGI mode %%MIXED%%.

You can also use HTTPD_set() to set variable CONVERT_RESPONSE_BODY to a value of NO (it defaults to AUTO which means the server will use content-type and content-encoding to determine if conversion is to be done) prior to your first call to HTTPD_write, to cause the server to do no conversion on the data in the buffer.