Contents of $_SESSION:
- sessTag:
a string of the format SESSION_NAME=SESSION_ID, for embedding in URLs.
(This is rarely used now; you use makeEventURL()
and makeEventForm()
instead.)
- dataDir:
the (absolute) directory on the server that all data for this user is
stored in.
- dataURL:
the (relative) URL for accessing user data. (Only correct for scripts
in public_html, not its
subdirectories. This will work for delegates in pages because they appear to be
public_html/index.php.)
- pages:
a stack of information about delegate pages in pages/. This is the mechanism
for the call-and-return, model-view-controller UI architecture provided
by index.php. See lib/event-page.php for details.
- currEventID:
also part of the MVC architecture. See lib/event-page.php for details.
- userIP:
the probable IP number of the current user. Not 100% reliable.
- timeZone:
a key into $TIME_ZONES (see timezones.php) for the user's preferred
time
zone.
- models:
an array of model-information entries (which are themselves arrays), as
described below.
- lastUsedModelID:
the ID of the last model used for any operation. It may also be null,
or may be an ensemble ID instead (model and ensemble IDs are guaranteed
to be disjoint sets for this reason). Helps
provide defaults for the user as they work through the MolProbity flow.
This is usually used in the display()
method of xxx_setup.php
pages. The preferred place to set it is in the event handling methods
of those same pages, but it may sometimes be more appropriate to do
that from a background script.
- ensembles:
an array of ensemble definitions, analogous to models, as
described below.
- edmaps:
an array of file names for electron density maps, which are stored in dataDir/MP_DIR_EDMAPS.
- archives:
an array of file names for temporary archive files, which are stored in
dataDir.
- hetdict:
the (absolute) path to a custom heterogen dictionary for Reduce. If
this is not set, the system default will be used instead.
- bgjob:
an array for storing information about the currently running background
job. This can serve both as input and output to the background script.
The only field that must be defined is isRunning;
this will be set automatically before the job is launched, but the job
itself is responsible for clearing this flag just before it exits.
Failing to clear this will make it appear that the job never exited and
instead ran forever.
- kingSize:
one of "tiny", "small", "default", "large", or "huge" - determines the
size of
the KiNG window.
Files present in the system data directory
($_SESSION[dataDir]/system):
You shouldn't ever be using the named files directly; instead, access
them
through the sessions and labbook APIs. Still, it's good to be aware
that they're here.
- session:
stores all the user session data.
- lifetime:
timestamps for the last time this session was accessed. Used for
garbage collection.
- labbook:
the serialized PHP data structure for all of the lab notebook entries.
Not (very) human readable.
- labbook.html:
human-readable HTML snapshot of the current labbook.
- progress:
the progress indicator for the background job. Controlled by setProgress().
- errors:
the output (stdout and stderr) from background jobs.
Issues to be aware of when working with files
- The Mac OS X filesystem (HFS) is case-preserving but not case-sensitive.
That means that files named "foo", "Foo", and "FOO" all refer to
exactly the same file, although the file system will list that file
with the capitalization you originally supplied. The PHP file_exists() function deals
with this correctly; i.e., if you touch
foo then file_exists("Foo")
== true.
- Users love to upload files with "weird" characters in their
names, especially spaces. See the censorFileName()
function in lib/core.php.
- Attackers would love to upload a file named session and overwrite your
session data, or to pass /etc/passwd
to a script that displays files. Remember that the apache account -- which runs
PHP -- has pretty generous permissions on your server. Think security
first when dealing with the file system!
- For that matter, attackers would be happy to upload .php or other
web-executable files (Perl, Python, Ruby, CGI, ...) to the server --
MolProbity allowed this for a long time. This basically allows
shell-level access to the web server as the Apache user. The censorFileName()
function can also guard against this by whitelisting allowed file
extensions.
- Permissions of files created by PHP are controlled by the umask() function; permissions
of directories are set at create time by mkdir().
Uploaded files often have very restrictive permissions that are
retained when they are moved or copied. If you're not sure, use chmod() to be safe! (And note
that chmod() takes an
octal argument, so be sure to prefix the number with a zero: e.g.,
0644).
Contents of $_SESSION['models']['myModelID']:
- id:
this is the key used for storing this model; labelled myModelID
above.
- prefix:
a string to be prepended to file names for generated files. Usually
something like "1ubq-" but it could even be the empty string. Example
name: $cbfile =
"{$prefix}cbeta.dat", assuming $prefix has already been
assigned this value.
Curly braces ensure proper variable interpolation; see the PHP manual
for explanation.
- pdb:
the filename for the PDB that is this current model. Full
path is $_SESSION['dataDir']."/".MP_DIR_MODELS."/".$_SESSION['models']['myModelID']['pdb'].
- stats:
the information returned by PdbStat for the PDB.
- segmap:
the segID-to-chainID mapping string that was applied to this file
(relative to its parent), or not set if none. This is specifically not a heritable property: one
remapping fixes the problem once and for all.
- parent:
the model ID of the model this one is "derived" from. For instance, a
model representing the results of reduce
-build might point back to the file pulled directly from the
PDB. This key is not set for models supplied by the user.
- history:
human-readable one-line statement about where this model came from.
- isUserSupplied:
true if the PDB file was supplied by the user (uploaded), rather than
retrieved from a public database.
- isReduced:
true if the PDB file has been processed by Reduce, so we know at a
minimum that all hydrogens are present. This is a heritable property.
- isBuilt:
true if the PDB is the result of a -build and/or -fix run in Reduce, so the
expert system has already changed all the Asn, Gln, and His that might
need changing. This is a heritable property.
Files created for each model:
All the actual file names are preceded by the model prefix.
Listed below are the suffixes. Order is alphabetical by file type, then
by file name. Not all files will necessarily be generated for every
model. [These are out of date and should be fixed...]
- multi.chart
- multiall.chart
- cbdev.data
- clash.data:
the result of running Clashlist.
- rama.data
- rota.data
- aac.kin:
all-atom contacts combined in one kin, with separate groups for
mainchain vs.
sidechain
- cbetadev.kin:
the "bullseye" kinemage plot of C-beta deviations for the whole
structure at once
- multi.kin:
the "multi-criterion" kinemage with all validation data at once
- rama.kin
- sswing.kin:
shows the results of running SSWING on a set of user-selected residues.
Similar to a flipkin.
- H.pdb:
the result of a reduce -build
run on some other model. Asn/Gln/His are flipped according to the
judgement of the expert system.
- mp.pdb:
the original uploaded/downloaded model file, as modified by preparePDB() (linefeeds, CNS
atom names, seg IDs).
- nbH.pdb:
the "nb" stands for "no build" - none of the existing atoms have been
moved, but missing hydrogens were added and optimized. Asn/Gln/His are
in their original orientations.
- Hfix.pdb:
the result of a reduce -build
-fix run, where the user choose which Asn/Gln/His should be
flipped. This should be different in some way than the H.pdb file.
- S.pdb:
the final SSWING PDB, which only includes user-approved changes.
- sswing.pdb:
throw-away PDB generated by the initial SSWING run, before user review.
- rama.pdf
Contents of $_SESSION['ensembles']['myEnsembleID']:
- id:
this is the key used for storing this ensemble; labelled myEnsembleID
above.
- prefix:
a string to be prepended to file names for generated files. Usually
something like "1ubq-" but it could even be the empty string. Example
name: $cbfile =
"{$prefix}cbeta.dat", assuming $prefix has already been
assigned this value.
Curly braces ensure proper variable interpolation; see the PHP manual
for explanation.
- models:
an array of model ID codes, identifying the models involved in this
ensemble. This should never be modified once an ensemble is created; a
new ensemble should be created instead.
- pdb:
a multi-model PDB file generated by joining the PDBs of the component
models.
- history:
human-readable one-line statement about where this ensemble came from.
- isUserSupplied:
true if the PDB file was supplied by the user (uploaded), rather than
retrieved from a public database.
- parent:
the ensemble ID of the ensemble this one is "derived" from. For
instance, an ensemble representing the results of reduce
-build might point back to the NMR file pulled directly from the
PDB. This key is not set for ensembles supplied by the user (as
multi-model files).
- isReduced:
true if the PDB file has been processed by Reduce, so we know at a
minimum that all hydrogens are present. This is a heritable property.
- isBuilt:
true if the PDB is the result of a -build and/or -fix run in Reduce, so the
expert system has already changed all the Asn, Gln, and His that might
need changing. This is a heritable property.
Contents of $_SESSION['bgjob']:
- isRunning:
this will be set automatically before the job is launched by launchBackground(), but the job
itself is responsible for clearing this flag just before it exits.
Failing to clear this will make it appear that the job never exited and
instead ran forever.
- processID:
the Unix PID of the parent background process. Can be used to abort
background jobs if necessary. Cleared by launchBackground().
- startTime:
Unix timestamp of job start time. Set by launchBackground().
- endTime:
Unix timestamp of when the job finished. Must be set by the job itself.
- refreshRate:
number of seconds between refreshes of the progress monitoring page.
Set by launchBackground().
- whereNext:
Name of the page to go to when job is finished, in the same form as
would be passed to pageGoto().
The context will automatically be set to $_SESSION['bgjob']. E.g. $_SESSION['bgjob']['whereNext'] =
"sitemap.php".
- ... plus other entries specific to the particular job at hand.
end