Annotation of doc/gutshtml/SessionThree.html, revision 1.2

1.2     ! bowersj2    1: <html>
        !             2: <head>
        !             3: <meta name=Title
        !             4: content=" Session Three: Roles and lonnet/loncommon useful functions (Guy)">
        !             5: <meta http-equiv=Content-Type content="text/html; charset=macintosh">
        !             6: <link rel=Edit-Time-Data href="Session%20Three_files/editdata.mso">
        !             7: <title> Session Three: Roles and lonnet/loncommon useful functions (Guy)</title>
        !             8: <style><!--
        !             9: .Section1
        !            10: 	{page:Section1;}
        !            11: .Section2
        !            12: 	{page:Section2;}
        !            13: -->
        !            14: </style>
        !            15: </head>
        !            16: <body bgcolor=#FFFFFF link=blue vlink=purple class="Normal" lang=EN-US>
        !            17: <div class=Section1><span style='font-size:12.0pt;font-family:Arial;'><b><i><br clear=ALL style='page-break-before:always'>
        !            18:   </i></b></span> 
        !            19:   <h2><a name="_Toc421867053">Session Three: Roles and lonnet/loncommon useful 
        !            20:     functions (Guy)</a></h2>
        !            21:   <h3><a name=name></a><a name="_Toc421867054">NAME</a></h3>
        !            22:   <p>Apache::lonnet - Subroutines to ask questions about things in the network.</p>
        !            23:   <div align=center style='text-align:center'> 
        !            24:     <hr size=2 width="100%" align=center>
        !            25:   </div>
        !            26:   <h3><a name=synopsis></a><a name="_Toc421867055">SYNOPSIS</a></h3>
        !            27:   <p>Invoked by other LON-CAPA modules, when they need to talk to or about objects 
        !            28:     in the network.</p>
        !            29:   <pre>&nbsp; &amp;Apache::lonnet::SUBROUTINENAME(ARGUMENTS);</pre>
        !            30:   <p>Common parameters:</p>
        !            31:   <ul type=disc>
        !            32:     <li>$uname : an internal username (if $cname expecting a course Id specifically) 
        !            33:     </li>
        !            34:     <li>$udom : a domain (if $cdom expecting a course's domain specifically) </li>
        !            35:     <li>$symb : a resource instance identifier </li>
        !            36:     <li>$namespace : the name of a .db file that contains the data needed or being 
        !            37:       set. </li>
        !            38:   </ul>
        !            39:   <div align=center style='text-align:center'> 
        !            40:     <hr size=2 width="100%" align=center>
        !            41:   </div>
        !            42:   <h3><a name=introduction></a><a name="_Toc421867056">INTRODUCTION</a></h3>
        !            43:   <p>This module provides subroutines which interact with the lonc/lond (TCP) 
        !            44:     network layer of LON-CAPA. And Can be used to ask about - classes - users 
        !            45:     - resources</p>
        !            46:   <p>For many of these objects you can also use this to store data about them 
        !            47:     or modify them in various ways.</p>
        !            48:   <p>This is part of the LearningOnline Network with CAPA project described at 
        !            49:     <a
        !            50: href="http://www.lon-capa.org./">http://www.lon-capa.org.</a></p>
        !            51:   <div align=center style='text-align:center'> 
        !            52:     <hr size=2 width="100%" align=center>
        !            53:   </div>
        !            54:   <h3><a name="return_messages"></a><a name="_Toc421867057">RETURN MESSAGES</a></h3>
        !            55:   <ul type=disc>
        !            56:     <li>con_lost : unable to contact remote host </li>
        !            57:     <li>con_delayed : unable to contact remote host, message will be delivered 
        !            58:       when the connection is brought back up </li>
        !            59:     <li>con_failed : unable to contact remote host and unable to save message 
        !            60:       for later delivery </li>
        !            61:     <li>error: : an error a occured, a description of the error follows the : 
        !            62:     </li>
        !            63:     <li>no_such_host : unable to fund a host associated with the user/domain that 
        !            64:       was requested </li>
        !            65:   </ul>
        !            66:   <div align=center style='text-align:center'> 
        !            67:     <hr size=2 width="100%" align=center>
        !            68:   </div>
        !            69:   <h3><a name="session_environment_functions"></a><a name="_Toc421867058">Session 
        !            70:     Environment Functions</a></h3>
        !            71:   <ul type=disc>
        !            72:     <li><code><span style='font-family:
        !            73:      Courier'>appenv(%hash)</span></code> : the value of %hash is written to the 
        !            74:       user envirnoment file, and will be restored for each access this user makes 
        !            75:       during this session, also modifies the %ENV for the current process </li>
        !            76:     <li><code><span style='font-family:
        !            77:      Courier'>delenv($regexp)</span></code> : removes all items from the session 
        !            78:       environment file that matches the regular expression in $regexp. The values 
        !            79:       are also delted from the current processes %ENV. </li>
        !            80:   </ul>
        !            81:   <h3><a name="user_information"></a><a name="_Toc421867059">User Information</a></h3>
        !            82:   <ul type=disc>
        !            83:     <li><code><span style='font-family:
        !            84:      Courier'>queryauthenticate($uname,$udom)</span></code> : try to determine 
        !            85:       user's current authentication scheme </li>
        !            86:     <li><code><span style='font-family:
        !            87:      Courier'>authenticate($uname,$upass,$udom)</span></code> : try to authenticate 
        !            88:       user from domain's lib servers (first use the current one), $upass should 
        !            89:       be the users password </li>
        !            90:     <li><code><span style='font-family:
        !            91:      Courier'>homeserver($uname,$udom)</span></code> : find the server which has 
        !            92:       the user's directory and files (there must be only one) . This caches the 
        !            93:       answer and also caches if there is an error.</li>
        !            94:     <li><code><span style='font-family:
        !            95:      Courier'>idget($udom,@ids)</span></code> : find the usernames behind a list 
        !            96:       of IDs (IDs are a unique resource in a domain, there must be only 1 ID per 
        !            97:       username, and only 1 username per ID in a specific domain) (returns hash: 
        !            98:       id=&gt;name,id=&gt;name) </li>
        !            99:     <li><code><span style='font-family:
        !           100:      Courier'>idrget($udom,@unames)</span></code> : find the IDs behind a list 
        !           101:       of usernames (returns hash: name=&gt;id,name=&gt;id) </li>
        !           102:     <li><code><span style='font-family:
        !           103:      Courier'>idput($udom,%ids)</span></code> : store away a list of names and 
        !           104:       associated IDs </li>
        !           105:     <li><code><span style='font-family:
        !           106:      Courier'>rolesinit($udom,$username,$authhost)</span></code> : get user privileges 
        !           107:     </li>
        !           108:     <li><code><span style='font-family:
        !           109:      Courier'>usection($udom,$uname,$cname)</span></code> : finds the section 
        !           110:       of student in the course $cname, return section name/number or '' for ``not 
        !           111:       in course'' and '-1' for ``no section'' </li>
        !           112:     <li><code><span style='font-family:
        !           113:      Courier'>userenvironment($udom,$uname,@what)</span></code> : gets the values 
        !           114:       of the keys passed in @what from the requested user's environment, returns 
        !           115:       a hash </li>
        !           116:   </ul>
        !           117:   <h3><a name="user_roles"></a><a name="_Toc421867060">User Roles</a></h3>
        !           118:   <ul type=disc>
        !           119:     <li><code><span style='font-family:
        !           120:      Courier'>allowed($priv,$uri)</span></code> : check for a user privilege; 
        !           121:       returns codes for allowed actions F: full access U,I,K: authentication modes 
        !           122:       (cxx only) '': forbidden 1: user needs to choose course 2: browse allowed 
        !           123:     </li>
        !           124:     <li><code><span style='font-family:
        !           125:      Courier'>definerole($rolename,$sysrole,$domrole,$courole)</span></code> : 
        !           126:       define role; define a custom role rolename set privileges in format of lonTabs/roles.tab 
        !           127:       for system, domain, and course level </li>
        !           128:     <li><code><span style='font-family:
        !           129:      Courier'>plaintext($short)</span></code> : return value in %prp hash (rolesplain.tab); 
        !           130:       plain text explanation of a user role term </li>
        !           131:   </ul>
        !           132:   <h3><a name="user_modification"></a><a name="_Toc421867061">User Modification</a></h3>
        !           133:   <ul type=disc>
        !           134:     <li><code><span
        !           135:      style='font-family:Courier'>assignrole($udom,$uname,$url,$role,$end,$start)</span></code> 
        !           136:       : assign role; give a role to a user for the level given by URL. Optional 
        !           137:       start and end dates (leave empty string or zero for ``no date'') </li>
        !           138:     <li><span style='font-family:
        !           139:      "Courier New"'>changepass($uname,$udom,$currentpass,$newpass,$server):</span> 
        !           140:       attempts to change a users, password, possible return values are: <span
        !           141:      style='font-family:"Courier New"'>ok, pwchange_failure, non_authorized, auth_mode_error, 
        !           142:       unknown_user, refused</span></li>
        !           143:     <li><code><span
        !           144:      style='font-family:Courier'>modifyuserauth($udom,$uname,$umode,$upass)</span></code> 
        !           145:       : modify user authentication </li>
        !           146:     <li><code><span
        !           147:      style='font-family:Courier'>modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene)</span></code> 
        !           148:       : modify user </li>
        !           149:     <li>modifystudent($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene,$usec, 
        !           150:       $end,$start) : modify student </li>
        !           151:     <li><code><span
        !           152:      style='font-family:Courier'>assigncustomrole($udom,$uname,$url,$rdom,$rnam,$rolename,$end,$start)</span></code> 
        !           153:       : assign custom role; give a custom role to a user for the level given by 
        !           154:       URL. Specify name and domain of role author, and role name </li>
        !           155:     <li><code><span
        !           156:      style='font-family:Courier'>revokerole($udom,$uname,$url,$role)</span></code> 
        !           157:       : revoke a role for url </li>
        !           158:     <li><code><span
        !           159:      style='font-family:Courier'>revokecustomrole($udom,$uname,$url,$role)</span></code> 
        !           160:       : revoke a custom role </li>
        !           161:   </ul>
        !           162:   <h3><a name="course_infomation"></a><a name="_Toc421867062">Course Infomation</a></h3>
        !           163:   <ul type=disc>
        !           164:     <li><code><span style='font-family:
        !           165:      Courier'>coursedescription($courseid)</span></code> : course description 
        !           166:     </li>
        !           167:     <li><span style='font-family:
        !           168:      "Courier New"'>courseresdata($coursenum,$coursedomain,@which) :</span> request 
        !           169:       for current parameter setting for a specific course, @what should be a list 
        !           170:       of parameters to ask about. This routine caches answers for 5 minutes.</li>
        !           171:   </ul>
        !           172:   <h3><a name="course_modification"></a><a name="_Toc421867063">Course Modification</a></h3>
        !           173:   <ul type=disc>
        !           174:     <li><code><span
        !           175:      style='font-family:Courier'>writecoursepref($courseid,%prefs)</span></code> 
        !           176:       : write preferences (environment database) for a course </li>
        !           177:     <li><code><span
        !           178:      style='font-family:Courier'>createcourse($udom,$description,$url)</span></code> 
        !           179:       : make/modify course </li>
        !           180:   </ul>
        !           181:   <h3><a name="resource_subroutines"></a><a name="_Toc421867064">Resource Subroutines</a></h3>
        !           182:   <ul type=disc>
        !           183:     <li><code><span style='font-family:
        !           184:      Courier'>subscribe($fname)</span></code> : subscribe to a resource, returns 
        !           185:       URL if possible (probably should use repcopy instead) </li>
        !           186:     <li><code><span style='font-family:
        !           187:      Courier'>repcopy($filename)</span></code> : subscribes to the requested file, 
        !           188:       and attempts to replicate from the owning library server, Might return HTTP_SERVICE_UNAVAILABLE, 
        !           189:       HTTP_NOT_FOUND, FORBIDDEN, OK, or HTTP_BAD_REQUEST, also attempts to grab 
        !           190:       the metadata for the resource. Expects the local filesystem pathname (/home/httpd/html/res/....) 
        !           191:     </li>
        !           192:   </ul>
        !           193:   <h3><a name="resource_information"></a><a name="_Toc421867065">Resource Information</a></h3>
        !           194:   <ul type=disc>
        !           195:     <li>EXT($varname,$symb,$udom, $uname) : evaluates and returns the value of 
        !           196:       a vairety of different possible values, $varname should be a request string, 
        !           197:       and the other parameters can be used to specify who and what one is asking 
        !           198:       about. </li>
        !           199:   </ul>
        !           200:   <p><span style='font-size:10.0pt'>Possible values for $varname are environment.lastname 
        !           201:     (or other item from the environment hash), user.name (or someother aspect 
        !           202:     about the user), resource.0.maxtries (or some other part and parameter of 
        !           203:     a resource)</span></p>
        !           204:   <ul type=disc>
        !           205:     <li><code><span
        !           206:      style='font-family:Courier'>directcondval($number)</span></code> : get current 
        !           207:       value of a condition; reads from a state string </li>
        !           208:     <li><code><span
        !           209:      style='font-family:Courier'>condval($condidx)</span></code> : value of condition 
        !           210:       index based on state </li>
        !           211:     <li><code><span
        !           212:      style='font-family:Courier'>metadata($uri,$what,$liburi,$prefix,$depthcount)</span></code> 
        !           213:       : request a resource's metadata, $what should be either a specific key, 
        !           214:       or either 'keys' (to get a list of possible keys) or 'packages' to get a 
        !           215:       list of packages that this resource currently uses, the last 3 arguments 
        !           216:       are only used internally for recursive metadata. This function automatically 
        !           217:       caches all requests</li>
        !           218:     <li><code><span
        !           219:      style='font-family:Courier'>metadata_query($query,$custom,$customshow)</span></code> 
        !           220:       : make a metadata query against the network of library servers; returns 
        !           221:       file handle of where SQL and regex results will be stored for query</li>
        !           222:     <li><code><span
        !           223:      style='font-family:Courier'>symbread($filename)</span></code> : return symbolic 
        !           224:       list entry (filename argument optional); returns the data handle </li>
        !           225:     <li><span style='font-family:
        !           226:      "Courier New"'>symbverify($symb,$thisfn):</span> verifies that $symb actually 
        !           227:       exists and is a possible symb for the URL in $thisfn, returns a 1 on success, 
        !           228:       0 on failure, user must be in a course, as it assumes the existance of the 
        !           229:       course init hash, and uses $ENV('request.course.id'}</li>
        !           230:     <li><span style='font-family:
        !           231:      "Courier New"'>symbclean($symb):</span> removes versions numbers from a symb, 
        !           232:       returns the cleaned symb</li>
        !           233:     <li><span style='font-family:
        !           234:      "Courier New"'>is_on_map($uri) :</span> checks if the $uri is somewhere on 
        !           235:       the current course map, user must be in a course for it to work</li>
        !           236:     <li><code><span
        !           237:      style='font-family:Courier'>numval($salt)</span></code> : return random seed 
        !           238:       value (addend for rndseed) </li>
        !           239:     <li><code><span
        !           240:      style='font-family:Courier'>rndseed($symb,$courseid,$udom,$username)</span></code> 
        !           241:       : create a random sum; returns a random seed, all arguments are optional, 
        !           242:       if they aren't sent it uses the environment to derive them. Note: if symb 
        !           243:       isn't sent and it can't get one from &amp;symbread it will use the current 
        !           244:       time as its return value </li>
        !           245:     <li><code><span
        !           246:      style='font-family:Courier'>ireceipt($funame,$fudom,$fucourseid,$fusymb)</span></code> 
        !           247:       : return unique, unfakeable, receipt </li>
        !           248:     <li><code><span
        !           249:      style='font-family:Courier'>receipt()</span></code> : API to ireceipt working 
        !           250:       off of ENV values; given out to users </li>
        !           251:     <li><code><span
        !           252:      style='font-family:Courier'>countacc($url)</span></code> : count the number 
        !           253:       of accesses to a given URL </li>
        !           254:     <li><code><span
        !           255:      style='font-family:Courier'>checkout($symb,$tuname,$tudom,$tcrsid)</span></code> 
        !           256:       : creates a record of a user having looked at an item, most likely printed 
        !           257:       out or otherwise using a resource </li>
        !           258:     <li><code><span
        !           259:      style='font-family:Courier'>checkin($token)</span></code> : updates that 
        !           260:       a resource has beeen returned (a hard copy version for instance) and returns 
        !           261:       the data that $token was Checkout with ($symb, $tuname, $tudom, and $tcrsid) 
        !           262:     </li>
        !           263:     <li><code><span
        !           264:      style='font-family:Courier'>expirespread($uname,$udom,$stype,$usymb)</span></code> 
        !           265:       : set expire date for spreadsheet </li>
        !           266:     <li><code><span
        !           267:      style='font-family:Courier'>devalidate($symb)</span></code> : devalidate 
        !           268:       temporary spreadsheet calculations, forcing spreadsheet to reevaluate the 
        !           269:       resource scores next time. </li>
        !           270:   </ul>
        !           271:   <h3><a name="storing/retreiving_data"></a><a name="_Toc421867066"><span
        !           272: style='"storing\/retreiving_data"'>Storing/Retrieving Data</span></a></h3>
        !           273:   <ul type=disc>
        !           274:     <li><code><span
        !           275:      style='font-family:Courier'>store($storehash,$symb,$namespace,$udom,$uname)</span></code> 
        !           276:       : stores hash permanently for this url; hashref needs to be given and should 
        !           277:       be a \%hashname; the remaining args aren't required and if they aren't passed 
        !           278:       or are '' they will be derived from the ENV </li>
        !           279:     <li><code><span
        !           280:      style='font-family:Courier'>cstore($storehash,$symb,$namespace,$udom,$uname)</span></code> 
        !           281:       : same as store but uses critical subroutine </li>
        !           282:     <li><code><span
        !           283:      style='font-family:Courier'>restore($symb,$namespace,$udom,$uname)</span></code> 
        !           284:       : returns hash for this symb; all args are optional </li>
        !           285:     <li><code><span
        !           286:      style='font-family:Courier'>tmpstore($storehash,$symb,$namespace,$udom,$uname)</span></code> 
        !           287:       : storage that works very similar to store/cstore, but all data is stored 
        !           288:       in a temporary location and can be reset using tmpreset, $storehash should 
        !           289:       be a hash reference, returns nothing on success </li>
        !           290:     <li><code><span
        !           291:      style='font-family:Courier'>tmprestore($symb,$namespace,$udom,$uname)</span></code> 
        !           292:       : storage that works very similar to restore, but all data is stored in 
        !           293:       a temporary location and can be reset using tmpreset. Returns a hash of 
        !           294:       values on success, error string otherwise. </li>
        !           295:     <li><code><span
        !           296:      style='font-family:Courier'>tmpreset($symb,$namespace,$udom,$uname)</span></code> 
        !           297:       : temporary storage reset, deltes all keys for $symb form the temporary 
        !           298:       storage hash. </li>
        !           299:     <li><code><span
        !           300:      style='font-family:Courier'>get($namespace,$storearr,$udom,$uname)</span></code> 
        !           301:       : returns hash with keys from array reference filled in from namesp ($udomain 
        !           302:       and $uname are optional) </li>
        !           303:     <li><code><span
        !           304:      style='font-family:Courier'>del($namespace,$storearr,$udom,$uname)</span></code> 
        !           305:       : deletes keys out of array from namesp ($udomain and $uname are optional) 
        !           306:     </li>
        !           307:     <li><code><span
        !           308:      style='font-family:Courier'>dump($namespace,$udom,$uname,$regexp)</span></code> 
        !           309:       : dumps the complete (or key matching regexp) namespace into a hash ($udomain, 
        !           310:       $uname and $regexp are optional) </li>
        !           311:     <li><code><span
        !           312:      style='font-family:Courier'>put($namespace,$storehash,$udomain,$uname)</span></code> 
        !           313:       : stores hash in namesp ($udomain and $uname are optional) </li>
        !           314:     <li><code><span
        !           315:      style='font-family:Courier'>cput($namespace,$storehash,$udomain,$uname)</span></code> 
        !           316:       : critical put ($udomain and $uname are optional) </li>
        !           317:     <li><code><span
        !           318:      style='font-family:Courier'>eget($namespace,$storearr,$udomain,$uname)</span></code> 
        !           319:       : returns hash with keys from array reference filled in from namesp (encrypts 
        !           320:       the return communication) ($udomain and $uname are optional) </li>
        !           321:     <li><code><span
        !           322:      style='font-family:Courier'>log($udom,$name,$home,$message)</span></code> 
        !           323:       : write to permanent log for user; use critical subroutine </li>
        !           324:   </ul>
        !           325:   <h3><a name="network_status_functions"></a><a name="_Toc421867067">Network Status 
        !           326:     Functions</a></h3>
        !           327:   <ul type=disc>
        !           328:     <li><code><span
        !           329:      style='font-family:Courier'>dirlist($uri)</span></code> : return directory 
        !           330:       list based on URI </li>
        !           331:     <li><code><span
        !           332:      style='font-family:Courier'>spareserver()</span></code> : find server with 
        !           333:       least workload from spare.tab </li>
        !           334:   </ul>
        !           335:   <h3><a name="apache_request"></a><a name="_Toc421867068">Apache Request</a></h3>
        !           336:   <ul type=disc>
        !           337:     <li><code><span
        !           338:      style='font-family:Courier'>ssi($url,%hash)</span></code> : server side include, 
        !           339:       does a complete request cycle on url to localhost, posts hash </li>
        !           340:   </ul>
        !           341:   <h3><a name="data_to_string_to_data"></a><a name="_Toc421867069">Data to String 
        !           342:     to Data</a></h3>
        !           343:   <ul type=disc>
        !           344:     <li><code><span
        !           345:      style='font-family:Courier'>hash2str(%hash)</span></code> : convert a hash 
        !           346:       into a string complete with escaping and '=' and '&amp;' separators, supports 
        !           347:       elements that are arrayrefs and hashrefs </li>
        !           348:     <li><code><span
        !           349:      style='font-family:Courier'>hashref2str($hashref)</span></code> : convert 
        !           350:       a hashref into a string complete with escaping and '=' and '&amp;' separators, 
        !           351:       supports elements that are arrayrefs and hashrefs </li>
        !           352:     <li><code><span
        !           353:      style='font-family:Courier'>arrayref2str($arrayref)</span></code> : convert 
        !           354:       an arrayref into a string complete with escaping and '&amp;' separators, 
        !           355:       supports elements that are arrayrefs and hashrefs </li>
        !           356:     <li><code><span
        !           357:      style='font-family:Courier'>str2hash($string)</span></code> : convert string 
        !           358:       to hash using unescaping and splitting on '=' and '&amp;', supports elements 
        !           359:       that are arrayrefs and hashrefs </li>
        !           360:     <li><code><span
        !           361:      style='font-family:Courier'>str2array($string)</span></code> : convert string 
        !           362:       to hash using unescaping and splitting on '&amp;', supports elements that 
        !           363:       are arrayrefs and hashrefs </li>
        !           364:   </ul>
        !           365:   <h3><a name="logging_routines"></a><a name="_Toc421867070">Logging Routines</a></h3>
        !           366:   <p>These routines allow one to make log messages in the lonnet.log and lonnet.perm 
        !           367:     logfiles.</p>
        !           368:   <ul type=disc>
        !           369:     <li><code><span
        !           370:      style='font-family:Courier'>logtouch()</span></code> : make sure the logfile, 
        !           371:       lonnet.log, exists </li>
        !           372:     <li><code><span
        !           373:      style='font-family:Courier'>logthis()</span></code> : append message to the 
        !           374:       normal lonnet.log file, it gets preiodically rolled over and deleted. </li>
        !           375:     <li><code><span
        !           376:      style='font-family:Courier'>logperm()</span></code> : append a permanent 
        !           377:       message to lonnet.perm.log, this log file never gets deleted by any automated 
        !           378:       portion of the system, only messages of critical importance should go in 
        !           379:       here. </li>
        !           380:   </ul>
        !           381:   <h3><a name="general_helper_routines"></a><a name="_Toc421867071">General File 
        !           382:     Helper Routines</a></h3>
        !           383:   <ul type=disc>
        !           384:     <li><code><span
        !           385:      style='font-family:Courier'>getfile($file)</span></code> : serves up a file, 
        !           386:       returns the contents of a file or -1; replicates and subscribes to the file 
        !           387:     </li>
        !           388:     <li><code><span
        !           389:      style='font-family:Courier'>filelocation($dir,$file)</span></code> : returns 
        !           390:       file system location of a file based on URI; meant to be ``fairly clean'' 
        !           391:       absolute reference, $dir is a directory that relative $file lookups are 
        !           392:       to looked in ($dir of /a/dir and a file of ../bob will become /a/bob) </li>
        !           393:     <li><code><span
        !           394:      style='font-family:Courier'>hreflocation($dir,$file)</span></code> : returns 
        !           395:       file system location or a URL; same as filelocation except for hrefs </li>
        !           396:     <li><code><span
        !           397:      style='font-family:Courier'>declutter()</span></code> : declutters URLs (remove 
        !           398:       docroot, beginning slashes, 'res' etc) </li>
        !           399:   </ul>
        !           400:   <h3><a name="_Toc421867072">HTTP Helper Routines</a></h3>
        !           401:   <ul type=disc>
        !           402:     <li><code><span
        !           403:      style='font-family:Courier'>escape()</span></code> : unpack non-word characters 
        !           404:       into CGI-compatible hex codes </li>
        !           405:     <li><code><span
        !           406:      style='font-family:Courier'>unescape()</span></code> : pack CGI-compatible 
        !           407:       hex codes into actual non-word ASCII character </li>
        !           408:   </ul>
        !           409: </div>
        !           410: <h1>&nbsp;</h1>
        !           411: <h3><a name="underlying_communication_routines_(shoul"></a><a
        !           412: name="_Toc421867073">Private: Underlying communication routines (Shouldn't call)</a></h3>
        !           413: <ul type=disc>
        !           414:   <li><code><span style='font-family:
        !           415:      Courier'>subreply()</span></code> : tries to pass a message to lonc, returns 
        !           416:     con_lost if incapable </li>
        !           417:   <li><code><span style='font-family:
        !           418:      Courier'>reply()</span></code> : uses subreply to send a message to remote 
        !           419:     machine, logs all failures </li>
        !           420:   <li><code><span style='font-family:
        !           421:      Courier'>critical()</span></code> : passes a critical message to another 
        !           422:     server; if cannot get through then place message in connection buffer directory 
        !           423:     and returns con_delayed, if incapable of saving message, returns con_failed 
        !           424:   </li>
        !           425:   <li><code><span style='font-family:
        !           426:      Courier'>reconlonc()</span></code> : tries to reconnect lonc client processes. 
        !           427:   </li>
        !           428: </ul>
        !           429: <h3><a name="resource_access_logging"></a><a name="_Toc421867074">Private: Resource 
        !           430:   Access Logging</a></h3>
        !           431: <ul type=disc>
        !           432:   <li><code><span style='font-family:
        !           433:      Courier'>flushcourselogs()</span></code> : flush (save) buffer logs and access 
        !           434:     logs </li>
        !           435:   <li><code><span style='font-family:
        !           436:      Courier'>courselog($what)</span></code> : save message for course in hash 
        !           437:   </li>
        !           438:   <li><code><span style='font-family:
        !           439:      Courier'>courseacclog($what)</span></code> : save message for course using 
        !           440:     &amp;courselog(). Perform special processing for specific resource types (problems, 
        !           441:     exams, quizzes, etc). </li>
        !           442:   <li><code><span style='font-family:
        !           443:      Courier'>goodbye()</span></code> : flush course logs and log shutting down; 
        !           444:     it is called in srm.conf as a PerlChildExitHandler </li>
        !           445: </ul>
        !           446: <h3><a name=other></a><a name="_Toc421867075">Private: Other</a></h3>
        !           447: <p><code><span style='font-family:"Courier New"'>symblist($mapname,%newhash)</span></code><span
        !           448: style='font-family:"Courier New"'> :</span> update symbolic storage links </p>
        !           449: <h3><a name="_Toc421867076">Coding Guidelines</a></h3>
        !           450: <p class=H5><span style='layout-grid-mode:
        !           451: both'>Things to keep in mind while coding handlers for LON-CAPA </span></p>
        !           452: <p><span
        !           453: style='font-size:14.0pt'>1.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           454:   </span></span><span style='font-size:14.0pt'>DON'T write to Access machine disks 
        !           455:   with permanent data, use store/restore </span></p>
        !           456: <p><span
        !           457: style='font-size:14.0pt'>2.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           458:   </span></span><span style='font-size:14.0pt'>DON'T </span><span
        !           459: style='font-size:14.0pt;font-family:"Courier New"'>use print()</span><span
        !           460: style='font-size:14.0pt'>, use </span><span style='font-size:14.0pt;font-family:
        !           461: "Courier New"'>$request-&gt;print()</span><span style='font-size:14.0pt'> </span></p>
        !           462: <p><span
        !           463: style='font-size:14.0pt'>3.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           464:   </span></span><span style='font-size:14.0pt'>DON'T launch children </span></p>
        !           465: <p><span
        !           466: style='font-size:14.0pt'>4.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           467:   </span></span><span style='font-size:14.0pt'>DO use </span><span
        !           468: style='font-size:14.0pt;font-family:"Courier New"'>$Apache::lonnet::perlvar{'lonDaemons'}/tmp</span><span
        !           469: style='font-size:14.0pt'> for temporary data. </span></p>
        !           470: <p><span
        !           471: style='font-size:14.0pt'>5.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           472:   </span></span><span style='font-size:14.0pt'>DO query the return value of every 
        !           473:   file operation. </span></p>
        !           474: <p><span
        !           475: style='font-size:14.0pt'>6.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           476:   </span></span><span style='font-size:14.0pt'>DO </span><span style='font-size:
        !           477: 14.0pt;font-family:"Courier New"'>use strict;</span><span style='font-size:
        !           478: 14.0pt'> </span></p>
        !           479: <p><span
        !           480: style='font-size:14.0pt'>7.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           481:   </span></span><span style='font-size:14.0pt'>DO </span><span style='font-size:
        !           482: 14.0pt;font-family:"Courier New"'>use strict;</span><span style='font-size:
        !           483: 14.0pt'> </span></p>
        !           484: <p><span
        !           485: style='font-size:14.0pt'>8.<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp; 
        !           486:   </span></span><span style='font-size:14.0pt'>DO familiarize your self with the 
        !           487:   functions in </span><span style='font-size:14.0pt;font-family:"Courier New"'>lonnet.pm</span><span
        !           488: style='font-size:14.0pt'> and use them to communicate with other servers and when 
        !           489:   you handler needs to ask questions. </span></p>
        !           490: <p>9.<span
        !           491: style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp; </span><span
        !           492: style='font-size:14.0pt'>DON'T use </span><span style='font-size:14.0pt;
        !           493: font-family:"Courier New"'>&amp;Apache::lonnet::reply()</span><span
        !           494: style='font-size:14.0pt'> </span></p>
        !           495: <br
        !           496: clear=ALL style='page-break-before:always;'>
        !           497: <div class=Section2> </div>
        !           498: </body>
        !           499: </html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>