req4c Concepts

Goto: 4C Home | 4C Docs | req4c Docs | req4c Function List req4c Concepts

req4c Concepts

In order to make best use of the req4c PHP interface, it is important to have a good understanding of the main concepts.

req4c Sessions

A req4c session is a way that state can be maintained between PHP req4c requests. From the PHP perspective a req4c session is a resource that is identified by a 24 byte cryptographically random base 64 string. The PHP application is free to save this string in any manner it sees fit. There is no secret information in this string. It can be saved in a cookie unencrypted. The req4c extension does not automatically save session ids. However, if you call req4c_open_session() without passing in a sessionid, req4c will look for a 'req4c_sessionid' cookie and use that when opening the session.

req4c does not automatically save any cookies. There are good reasons for this including:

The PHP program may have already output data by the time it creates a req4c session. If so, then it is too late to save a cookie.
The PHP application may be using multiple req4c sessions. In that case the PHP application needs to choose different names for different session ids if it wishes to save them as cookies.
I think the application should be in charge of what cookies are saved.
It's a real simple task for the PHP program to set a cookie and name it as any way it chooses.

req4c sessions allow the PHP program to set session wide variables that are guranteed to be set any time the session that set the vars is open. These variables are never sent to the client browser. They are stored with session information in memory by the 4creqd process and sent automatically to the PHP program when a session is opened. The PHP program can set session vars usin the $_REQ4C_SESSION super global array. For example: $_REQ4C_SESSION['username'] = 'kjenglish'

From the 4creqd perspective, a session is this same session id along with other information stored only in memory by the 4creqd process. The other information includes:

Two configurable fingerprints used to prevent the session id from being used by any client other than the one who created it. One of these fingerprints is used when SSL is not used and both are used when SSL is used.
Session variables set by the PHP program.

When a session is first created, it is associated with a single 4C server and 4C application. A single req4c session cannot be used to access different 4C servers or even different 4C applications on the same server. If your application needs to access multiple 4C servers, then it needs to use multiple req4c sessions.

4creqd has configuration options that allow you to specify the maximum length of time that a session can exist before being destroyed and the maximum time a session can remain idle before being destroyed.

When a session is in use, and a 4C program is run, 4creqd always sends the session id and the create time of the session to the 4csrvr process. The 4csrvr process can access these two values using the system variables sys.web_sid and sys.web_sts. The 4csrvr process, can then maintain state in whatever way is most suitable to the application. One real important thing to keep in mind about maintaining state is that there is no guarantee that 2 different calls, even if made by the same PHP script, to run 4C programs will be processed by the same 4csrvr process. This means you cannot use the FC_SESSION directory to store anything you expect to access in more then one req4c requests.

It is not necessary to use req4c sessions. req4c will not automatically use sessions. If you want to use sessions, you must explicitly create and open them. They are there as a tool to help the application maintain state when needed. It is assumed that most applications will need to maintain some state, so hopefully req4c sessions will be useful.

If you prefer to use PHP sessions req4c will send the PHP sessionid to the 4csrvr when running a 4C program and you can access this value using the system variable sys.web_phpsid.

You may even find it useful to combine req4c sessions with PHP sessions.

req4c ResultSets

A req4c ResultSet is everything sent from the 4csrvr process to the PHP program, except error messages and info messages. This includes:

Data sent as part of a Web enabled report
Data sent as part of a sys.send_result() system PCL call,
The program name and result type of each row in the ResultSet
The number of results in the ResultSet
The exit code of the 4C program.
Information on every ResultRow in the ResultSet

Though, Error messages and Information messages may be generated by a 4C program and accessed by a PHP program, they are not part of the req4c ResultSet.

A req4c ResultSet, though similar to an SQL ResultSet, has some significant differences.

The ResultRows in a req4c ResultSet are not necessarily homogenous. One ResultRow may have 3 columns of data and the next may have only one. This is because different sub reports, by definition, are sending different types of data. There are req4c functions for determining what 4C program and what 4C report/type generated any particular ResultRow in the req4c ResultSet.
When 4C data is updated, there is no way to know number of "rows" updated, unless the application explicitly sends this as a ResultRow using sys.send_result(), as the exit code of the 4C program, or as an informational message using sys.message().

From the PHP perspective, a req4c ResultSet is a resource returned by the req4c_run() function call that persists until the PHP script ends or the resource is unset. It is possible for a PHP script to save multiple ResultSets in different variables.

Once a req4c ResultSet is returned to the PHP program, it can be queried in many ways. No req4c function call that queries a req4c ResultSet require any network access. It is all internal to the PHP engine.

req4c ResultRows

A req4c ResultRow is a single row of data generated by a 4C program. You must have a ResultSet resource in order to access any of the ResultRows. From a PHP perspective a ResultRow is always an array of strings. Depending on how you fetch the ResultRow, the array may be indexed numerically or keyed by the ResultRow column names. There are req4c functions for getting the 4C program name that generated a ResultRow and for getting the type of the ResultRow. The type of the ResultRow will either be the report name that generated the row, or the type passed to sys.send_result(). There may be places in the documentation where a ResultRow is referred to simply as a result and sometimes simply as a row. Both are the same as ResultRow.

req4c Information and Error Messages

req4c maintains a list of error messages and info messages. These messages can be accessed by the PHP program. Information and/or Error messages may be generated by:

A 4C program started by the req4c_run() function. These messages are generated when the 4C program calls sys.msg(), sys.err_msg() or sys.message(). Info messages generated by sys.msg() or sys.message(SM_INFO|SM_NOWAIT,...) are not guaranteed to be sent to the client. Only the the last info message generated this way when 4csrvr flushes it's network send buffer is sent. The only way to guarantee that an info message is sent is to use sys.message(SM_INFO|SM_WAIT,...). The SM_WAIT, will be ignored, but the message will be sent.
The 4creqd process. These are generated when a req4c function makes a call that requires a round trip request to 4creqd. Informational messages are usually only sent when running a debug version of 4creqd. Error messages are sent if the request cannot be handled and are meant to help the application understand why.

In addition to the above, the lib4cphp library will set a single error_num and a single error_msg separate from the error message list when the req4c function call fails. This message is always cleared at the start of any req4c function, except req4c_get_error_msg() and req4c_get_error_num().

There are req4c functions for

Getting the number of error messages
Getting the number of informational messages
Getting an error message from the error message list
Getting an informational message from the info message list
Getting the error message of the last req4c function call.

Any req4c function that may generate error messages always clears the current message list first. If you need to process error/info messages, you need to either save them in a PHP variable for processing or make sure you do the processing before you call a req4c function that clears the list.

See the Comments section for each individual function to see if it clears the current message list or not.

Most req4c functions also clear the last error info which is stored in $_REQ4C['errno'] and $_REQ4C['errmsg']. The only ones that currently don't are:

req4c_get_apprc()
req4c_get_num_errors()
req4c_get_num_msgs()
req4c_get_num_results()
req4c_get_error_num()
req4c_get_error_msg()

req4c Function Call Processing

In order to have a responsive application it is important to know where network requests occur. Most req4c functions involve no network requests of any kind. There are some that involve round trip requests to the 4creqd process only. When the 4creqd process is on the same machine as the Web Server, these round trip requests can be extremely fast if the 4creqd server is configured to use domain sockets.

There is one req4c function, req4c_run() , that requires a round trip request between the PHP request and the 4creqd process as well as a round trip between the 4creqd process and a 4csrvr process. So rather than make one req4c_run() call to get a list and then make another req4c_run() call for every item in the list, it is better to design a program that can return all the needed information in one req4c_run() request. Of course, you need to be careful and make sure you are not returning 10s of thousands of rows at a time also.

The documentation for each of the req4c PHP functions includes types of network requests used in the Comments section.

Process Timing

Every request that communicates with the 4creqd process must first be authenticated. When the 4creqd process is running on the same machine as the Web Server, then this authentication will normally use the credentials of the connection to authenticate the process. This requires one round trip network request before the request is sent. The request itself, then requires another round trip network request. When domain sockets are in use, these types of round trip network requests are quite fast. This authentication is done only once per PHP request cycle. If one PHP request cycle makes multiple calls to req4c, the authentication is still only done on the first req4c request. A PHP request cycle is the running of one script from start to finish. A guess you would call this a PHP program instance also.

When a request requires communicating with a 4csrvr process, the 4creqd process first determines if it has a connection available with the proper authentication and then uses that connection for the request. If necessary, 4creqd will initiate another connection to a new 4csrvr process. This initiation is very slow and for this reason, 4creqd maintains a pool of threads with existing connections so that the initiation process does not need to occur frequently. There are configuration options that allow you to specify how large the thread pool should be and how many connections to maintain.

Superglobals

req4c defines two superglobal (also called autoglobal) arrays, $_REQ4C and $_REQ4C_SESSION. $_REQ4C always contains at least the following:

$_REQ4C['errno'] - An integer error_num from the last req4c function call.
$_REQ4C['errmsg'] - The error_msg string from the last req4c function call.
$_REQ4C['sessionid'] - The sessionid string of the current req4c session if there is one or the empty string if there is not.

Your PHP programs can query these values, but should not modify them.

$_REQ4C_SESSION is empty unless there is a req4c session open. If there is a req4c session open, then this array has all the variables that any PHP program has set into it. All your program needs to do to store variables is something like: $_REQ4C_SESSION['phone'] = '�'
The values you set in this array are stored in memory by 4creqd and sent to req4c everytime a session is opened.

Back to Top