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.
The following DDS field types are handled:
- A - Alphanumeric (see note 1 below)
- P - Packed Decimal (see note 2 below)
- S - Zoned Decimal
- F - Floating Point
- T - Time
- L - Date
- Z - Timestamp
- B - Binary (see note 3 below)
- O - DBCS
The following DDS field types are not handled:
- H - Hexadecimal (see note 4 below)
- G - Graphic
- J - DBCS
- E - DBCS
- The VARLEN keyword is not supported.
- When using a packed decimal field, the #pragma mapinc() must use _P the option, to create a packed structure.
- 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).
- 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