When building a prepared statement, the PDO core will allocate and initialize an instance of the pdo_stmt_t type and pass it to the SKEL_prepare_func function. The stmt passed to the preparer will have query_string and query_stringlen initialized, along with some other state that is not relevant to a driver implementation. The preparer is responsible for setting up the driver specific portion of the prepared statement state. This typically involves invoking the PDO query rewriter and then passing the resultant query string to a database client library API that sets up the prepared statement handle. The stmt has the following fields that can be set by the preparer function: methods This field must be set by the preparer before it returns, even if the prepare failed. This allows the core to correctly interrogate the statement handle if an error occurs. driver_data The driver_data field can be used by the driver to store an arbitrary pointer to some state. This is typically a structure that holds the statement context used by the underlying database client library and any other additional state needed by the driver. supports_placeholders The driver should set this to either PDO_PLACEHOLDER_NONE or one or both of PDO_PLACEHOLDER_NAMED or PDO_PLACEHOLDER_POSITIONAL bitwise OR'd together. This indicates to the query rewriter what level of parameter subsitution is supported natively by the driver. named style placeholders are Oracle style named parameters whereas positional style parameters are ODBC style question mark parameter placeholders. named_rewrite_template Some drivers may only support alternative named parameter syntax that is not recognized by PDO. Those drivers may set named_rewrite_template to a printf style format string that can be used by the query rewriter to map the ordinal position of a parameter to a name that is recognized by the driver. snprintf will be invoked using this string as the format specifier, and will be passed a single integer parameter representing the ordinal position of the parameter. The PostgreSQL driver sets named_rewrite_template to $%d, which allows PDO to rewrite Oracle style named parameters to position style, and from there, uses the rewrite template to map them to the PostgreSQL named format. A driver must set supports_placeholders to PDO_PLACEHOLDER_NAMED to make use of this feature. If the driver natively supports both placeholder styles, it can pass query_string through to its native prepare API. Otherwise, it must set supports_placeholders appropriately and then invoke pdo_parse_params to analyze and possibly rewrite the query string. If an error is encountered, the preparer function should record error state in the dbh rather than the stmt as a failed prepare will result in the stmt being freed and it will thus not be available for interrogation. The state recorded in the dbh must be compatible with the error handling protocol described in . Returns 1 on success, 0 on failure.

PDO_API int pdo_parse_params(pdo_stmt_t *stmt, char *inquery, int inquery_len, char **outquery, int *outquery_len TSRMLS_DC); Given an input inquery and its length, inquery_len, analyzes the SQL and potentially rewrites it to an appropriate native form based on the supports_placeholders field in stmt. Returns 0 if the input query is in a suitable native form that the driver understands. Returns 1 if the query was rewritten; outquery and outquery_len will be updated to reference the rewritten query string and its length. If outquery is not NULL, the caller is responsible for freeing it via efree when it is no longer required. Returns -1 if an error ocurred. The error_code field of stmt will have been set to an appropriate SQLSTATE error code. A driver will usually copy this code into the equivalent field of the dbh.