=====
CS 328 - Week 10 Lecture 1 - 2024-03-25
=====

=====
TODAY WE WILL
=====
*   announcements
*   start connecting the application tier and the data tier -
    getting PHP to request stuff from Oracle
*   prep for next class

=====
*   should be working on Homework 8,
    first attempts due by 11:59 pm on Sunday, March 31

*   and should be working through zyBooks Chapter 5 - PHP Fundamentals

=====
*   there are MULTIPLE packages for allowing a PHP engine
    on an application tier to request actions from the data tier;

    we want to request actions from an Oracle databases,
    so we want to use one of the packages for that,

    and the one supported for the PHP engine on nrs-projects
    that can talk to the Oracle student database on campus
    is OCI - Oracle Call Interface

====
*   in OCI,
    you first need to establish a connection between
    the PHP engine and Oracle

    oci_connect is a function you can use for this.

    you call oci_connect with appropriate arguments,
    it returns a connection object you can use to do stuff.

*   (and because the number of connections to the Oracle db
    on campus is finite,
    class style is to explicitly CLOSE you connection,
    using
    
    oci_close with your connection object as its argument,

    ...as soon as you are done with the connection!!!!!!!!!!!!!!!!

====
QUICK NOTE -- variable interpolation addition
====
*   in double quotes, you can surround
    the variable name with { } when you want to grab a variable
    value and stick it inside non-blank stuff

    $ora_php_username = "{$os_username}_php";

*   BUT -- say you have gotten a connection object using oci_connect.

    BEFORE you close it using oci_close -- what can you DO with the
    connection?
    *   if the PHP document wants to ask the data tier/Oracle to
        do a static query/select statement, it can:

        (static? means it is not dynamic, it is the same hard-coded
        unchanging query each time -- as opposed to one that gets
        adapted or built based on user input, for example)

        *   use oci_parse to set up a query and get a statement object,
        *   oci_execute to execute it,
        *   oci_fetch to get access to the next row in the result,
        *   and oci_result to grab a particular value from that row

        *   when done with the statement object,
            free it using oci_free_statement
            
        *   and when done with the connection object,
            use oci_close to close the connection!
  
    *   we ran out of time in this class,
        but because oci_fetch returns a "truthy" value if it succeeded
        in setting up access to a next row and returns a "falsy" value
        if it could not,

        a common pattern is to use the call to oci_fetch as the bool
        expression in a while loop, to do something with each row selected:

        ...oci_parse...
        ...oci_execute...

        while (oci_fetch(...))
        {
           ... oci_result ...
        }

        oci_free_statment(...);
        oci_close(...);