Convert to DB (QtmhCvtDB) API

The QtmhCvtDB() API provides an interface for CGI programs to parse CGI input, defined as a series of keywords and their values, into a buffer which is formatted according to a DDS file specification.

Required Parameter Group:
1 Qualified database file name Input Char(20)
2 Input string Input Char(*)
3 Length of input string Input Binary(4)
4 Response variable Output Char(*)
5 Length of response variable Input Binary(4)
6 Length of response available Output Binary(4)
7 Response code Output Binary(4)
8 Error Code I/O Char(*)

CGI input data, which comes to the CGI program as character data, will be converted by the QtmhCvtDB() API to the data type defined for the keyword by the corresponding field name in the input DDS file. Language statements, such as the ILE C #pragma mapinc statement, provide the ability to map the returned structure with field names defined in the DDS file. See the appropriate language user's guide for details.

Note: QtmhCvtDB() API is not allowed in CGI mode %%BINARY%%.

The following DDS field types are handled:

The following DDS field types are not handled:

Notes:
  1. The VARLEN keyword is not supported.
  2. When using a packed decimal field, the #pragma mapinc() must use _P the option, to create a packed structure.
  3. Input to Binary fields is converted to integer. The DDS file specification must declare zero decimal positions (for example, “xB 0”, where x is 1-9).
  4. ILE C converts hex DDS field data to character fields. Since the input stream to QtmhCvtDB() is a text string, the “hex” data would be converted from text to character fields. Therefore, using the A (Alphanumeric) field type to obtain the same conversion.

Required parameter group

Qualified database file name
Input:CHAR(20)

The input variable containing the name of the database file defining field names and data types for the keywords anticipated in the input to the CGI program. Typically, the database file is generated using DDS to define the fields corresponding to the keywords anticipated in the CGI inputs. The first 10 characters contain the database file name, and the second 10 characters contain the library name.

Input string
INPUT:CHAR(*)

The input variable containing the string of CGI input parameters to be parsed. When the environment variable REQUEST_METHOD indicates that the method is GET, characters up to the first ? are ignored. The string must meet the format requirements for CGI input keyword strings.

Length of input string
INPUT:BINARY(4)

The input variable containing the length of the character string that contains the CGI input parameters to be parsed. The length of the string must be greater than 0.

Response variable
OUTPUT:CHAR(*)

The output variable which is to contain the structure mapped according to the database file describing the input parameters anticipated by the CGI program.

Length of response available
INPUT:BINARY(4)

The input variable containing the total length of the buffer into which the CGI input parameters will be parsed.

Length of response
OUTPUT:BINARY(4)

The output variable that contains the length of the response. If the response variable is too small to contain the entire response, this parameter will be set to the size that is required to contain the entire response.

Response code
OUTPUT:BINARY(4)

A code that indicates the status of the request.

  • 0 - All keywords have been translated according the database file.
  • -1 - The database file contains definitions for structure fields for which the CGI input has no corresponding keyword.
  • -2 - The CGI input contains one or more keywords for which the database file contains no corresponding field.
  • -3 - A combination of the condition for response codes -1 and -2 has been detected.
  • -4 - An error occurred while converting the CGI input string to the DDS defined data types. The data may or may not be usable.
  • -5 - This API is not valid when a program is not called by HTTP Server. No data parsing is done.
  • -6 - This API is not valid when operating in %%BINARY%% mode. No data parsing is done.
Error Code
I/O CHAR(*)

The structure in which to return error information. For the format of the structure and for details on how to process API errors, see the API error reporting topic in the IBM® i Information Center.

Error messages

CPF24B4 E
Severe Error while addressing parameter list.
CPF3C17 E
Error occurred with input data parameter.
CPF3C19 E
Error occurred with receiver variable specified.
CPF3CF1 E
Error code parameter not valid.
CPF9810 E
Library &1 not found.
CPF9812 E
File &1 in library &2 not found.
CPF9822 E
Not authorized to file &1 in library &2