## 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