Update INI documentation for ibm_db2

[NattyNarwhal]

A bunch of previously undocumented stuff, including things that are ugly and probably should be deprecated.

Note some of these are platform-specific; I have tried to word based on this ("on IBM i" vs. "when connecting to IBM i"), but I've considered adding a column, if that would make sense.

[Girgias]

Minor nits but looks good overall

[alanseiden]

@NattyNarwhal The historical use case for null user and password was to stay out of Server Mode, i.e. not connect to a QSQSRVR job. The database is accessed directly inside PHP. It was a performance optimization. The danger is not only being limited to the web server user, (in the case of a web application), but that database resources could potentially linger in the PHP job.

[NattyNarwhal]

Null username/password avoiding spawning a server job isn't documented elsewhere for ibm_db2; the underlying SQLConnect mentions non-server mode, but implies you can just use server mode where null uid/pwd still uses a server, just with current profile. So how does it handle to use server vs. in process?

Checking ibm_db2, it does set the environment attribute to use a here, if this option is off:

            if (IBM_DB2_G(i5_ignore_userid) < 1 && !is_i5_server_mode) {
                attr = SQL_TRUE;
                rc = SQLSetEnvAttr((SQLHENV)conn_res->henv, SQL_ATTR_SERVER_MODE, (SQLPOINTER)(intptr_t)attr, SQL_IS_INTEGER);
                if (rc == SQL_SUCCESS) {
                    is_i5_server_mode=1;
                }
            }

...and it checks the option here for if it should set the job's subsystem if using a server:

        /* 1.9.7 - IBM i consultant request switch subsystem QSQSRVR job (customer workload issues) */
        if (IBM_DB2_G(i5_servermode_subsystem) && strlen(IBM_DB2_G(i5_servermode_subsystem)) > 0 && IBM_DB2_G(i5_ignore_userid) < 1) {
            rc = SQLSetConnectAttr((SQLHDBC)conn_res->hdbc, SQL_ATTR_SERVERMODE_SUBSYSTEM, (SQLPOINTER) IBM_DB2_G(i5_servermode_subsystem), SQL_NTS);
        } 

...so this option is kind of misleadingly named - it should be more like "run database job in the same job as PHP". That's a lot to describe. And the funny thing is I think you can still use a different profile for same-job, it just suppresses the passed options to SQLConnect if so:

#ifdef PASE /* 1.9.7 - IBM i cosolidate connect differences/options (code clarity) */
            /* If the string contains a =, use SQLDriverConnect */
            if ( strstr(database, "=") != NULL ) { 
                /* IBM i unqualified connect requires output buffer (long time ibm_db2 bug) */
                rc = SQLDriverConnect((SQLHDBC)conn_res->hdbc, (SQLHWND)NULL,
                        (SQLCHAR*)database, SQL_NTS, i_buffer, 255, &i_outlen, SQL_DRIVER_NOPROMPT );
            } else { /* IBM i allow/not blank db, uid, pwd (customer request vs. security issue) */
                if (IBM_DB2_G(i5_ignore_userid) > 0 || (IBM_DB2_G(i5_blank_userid) > 0 && uid_len == 0 && password_len == 0) ) {
                    rc = SQLConnect( (SQLHDBC)conn_res->hdbc, (SQLCHAR *)database,
                            (SQLSMALLINT)database_len, (SQLCHAR *)NULL, (SQLSMALLINT)0,
                            (SQLCHAR *)NULL, (SQLSMALLINT)0);
                } else { /* normal uid/pwd connection */
                    rc = SQLConnect( (SQLHDBC)conn_res->hdbc, (SQLCHAR *)database,
                        (SQLSMALLINT)database_len, (SQLCHAR *)uid, (SQLSMALLINT)uid_len,
                        (SQLCHAR *)password, (SQLSMALLINT)password_len );
                }
            }
#else /* LUW */
            /* If the string contains a =, use SQLDriverConnect */
            if ( strstr(database, "=") != NULL ) {
                rc = SQLDriverConnect((SQLHDBC)conn_res->hdbc, (SQLHWND)NULL,
                        (SQLCHAR*)database, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT );
            } else {
                rc = SQLConnect( (SQLHDBC)conn_res->hdbc, (SQLCHAR *)database,
                        (SQLSMALLINT)database_len, (SQLCHAR *)uid, (SQLSMALLINT)uid_len,
                        (SQLCHAR *)password, (SQLSMALLINT)password_len );
            }
#endif /* PASE */

[alanseiden]

@NattyNarwhal Thanks for confirming and clarifying. Yes, Tony sometimes named things literally in a technical sense, not so much what the purpose was. Yes, the purpose is to run the database job in the same job as PHP. Should we provide an alias called "i5-use-client-job" or something?

[NattyNarwhal]

I think it should probably be renamed in ibm_db2, but that's a separate issue (tracking here). For now, we should document the existing behaviour in this PR.

[NattyNarwhal]

This doesn't include i5_check_pconnect, but that option is Not Good and contains some suspect functionality.

[Girgias]

Thank you!