home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / bu1_os2.zip / U1_Hooks.INF (.txt) < prev    next >
OS/2 Help File  |  1995-05-09  |  17KB  |  343 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Title Page ΓòÉΓòÉΓòÉ
  3.  
  4.  
  5. ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ
  6.  
  7.                                   U1 Rexx Hooks
  8.  
  9.                                 Guide & Reference
  10.  
  11.                                   Beta Version!
  12.  
  13.                                 Dmitry Zavalishin
  14.  
  15.               Artworks by Dmitry Zavalishin and Kira Stratonnikova
  16.  
  17.                                   Moscow, 1995
  18.  
  19.  
  20. ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ
  21.  
  22.  
  23. ΓòÉΓòÉΓòÉ 2. What is REXX hook? ΓòÉΓòÉΓòÉ
  24.  
  25. There it a lot of things in a gate, that differrent people like to be done some 
  26. unusual way. Examples are address translation, data compression, accounting, 
  27. etc etc.  Instead of adding to the U1 all of the possible ways of doing those 
  28. things and, thus, making it grow bigger, it's configs to become clumsier, I 
  29. decided to let users control the way gate works themselves by writing scripts 
  30. in REXX that will intercept some data, processed by gate and convert that data 
  31. the way user likes.  The best example of such hook is UU2Fido uucp address 
  32. hook, which is called before gateing letter and given uucp address this letter 
  33. is addressed to.  Hook script can convert that address to anything user seems 
  34. to be appropriate and then return new address for gate to use instead of the 
  35. original one. If no hook provided, address will be passed as is to U1 uucp to 
  36. fido address convertor. 
  37.  
  38.  
  39. ΓòÉΓòÉΓòÉ 3. How can I write my own REXX hook? ΓòÉΓòÉΓòÉ
  40.  
  41. Every OS/2 system has a simple book on REXX language. Please make sure you're 
  42. familiar enough with REXX before trying to use REXX hooks. Each hook is 
  43. described separately  below, please read carefully about hook arguments, return 
  44. value and situation, in which that hook is called. REXX hook is a rexx program 
  45. file, which name is given in corresponding U1 setup file parameter. Most hooks 
  46. are started with arguments and all of them must return some value. 
  47.  
  48.  Hook parameters 
  49.            The following line of REXX code will retrieve first argument of REXX 
  50.            hook into the variable 'First_Arg': 
  51.  
  52.                       Parse Arg First_Arg
  53.  
  54.  Return values 
  55.            The following line of REXX code will return result of script to the 
  56.            caller and terminate execution of script: 
  57.  
  58.                       /**
  59.                        * Assume that variable 'result' contains the value we
  60.                        * want to return.
  61.                       **/
  62.                       Return result
  63.  
  64.            If no return value is needed for the hook you're writing, return 0 
  65.            (zero) on success and -1 on failure. 
  66.  
  67.                       /**
  68.                        * We're failed, failed, failed :(
  69.                       **/
  70.                       Return -1
  71.  
  72.  
  73. ΓòÉΓòÉΓòÉ 4. Additional REXX operators ΓòÉΓòÉΓòÉ
  74.  
  75. When writing U1 REXX hooks you can use additional operators, described below. 
  76. Please don't forget that additional operators are defined in "U1" environment 
  77. only, and if you change environment with 'ADDRESS' operator all of them will be 
  78. unavailable. To switch environment back use 'ADDRESS "U1"' command. See Rexx 
  79. reference book, keyword instruction 'ADDRESS' for further information on 
  80. environments. 
  81.  
  82.  
  83. ΓòÉΓòÉΓòÉ 4.1. Operator 'log': Writing debug info to U1 log file ΓòÉΓòÉΓòÉ
  84.  
  85.  Purpose 
  86.            Can be used to write debugging information to U1 log file. 
  87.  
  88.  Parameters 
  89.            Text to be logged. 
  90.  
  91.  Notes 
  92.            U1 setup parameter LogLevel must have 'x' character in it's value, 
  93.            or debug mode must be turned on in oprder for log operator to be 
  94.            effective. 
  95.  
  96.  Sample 
  97.  
  98.                       /* Log value of variable 'input' */
  99.                       log 'Rexx Hook is running. Parameter is: 'input
  100.  
  101.  
  102. ΓòÉΓòÉΓòÉ 4.2. Operator 'warning': Displaying warning message ΓòÉΓòÉΓòÉ
  103.  
  104.  Purpose 
  105.            Can be used to warn user about unususal conditions. 
  106.  
  107.  Parameters 
  108.            Text to be displayed and logged. 
  109.  
  110.  Notes 
  111.            Text will be prepended with 'Warning: ' before displaying it. 
  112.  
  113.  Sample 
  114.  
  115.                       /* Issue a warning message */
  116.                       warning 'Address 'in_address' seems to be strange.'
  117.  
  118.  
  119. ΓòÉΓòÉΓòÉ 4.3. Operator 'error': Displaying error message ΓòÉΓòÉΓòÉ
  120.  
  121.  Purpose 
  122.            Can be used to tell user about non-fatal error. 
  123.  
  124.  Parameters 
  125.            Text to be displayed and logged. 
  126.  
  127.  Notes 
  128.            Text will be prepended with 'Error: ' before displaying it. 
  129.  
  130.  Sample 
  131.  
  132.                       /* Issue an error message */
  133.                       error 'No username in address 'in_address'. Forwarding letter to postmaster.'
  134.  
  135.  
  136. ΓòÉΓòÉΓòÉ 4.4. Operator 'fatal': Displaying fatal error message and halting ΓòÉΓòÉΓòÉ
  137.  
  138.  Purpose 
  139.            Can be used to tell user about fatal error. 
  140.  
  141.  Parameters 
  142.            Text to be displayed and logged. 
  143.  
  144.  Notes 
  145.            Text will be prepended with 'Fatal: ' before displaying it. 
  146.  
  147.                       CAUTION:
  148.            Executing operator 'fatal' you'll stop currently running gate module 
  149.            non-gracefully, possibly loosing some data (letters or articles). 
  150.  
  151.  Sample 
  152.  
  153.                       /* Issue an error message and terminate gate */
  154.                       fatal 'Out of disk space!'
  155.  
  156.  
  157. ΓòÉΓòÉΓòÉ 5. Sample (NULL) script (Rexx.U2F.Address) ΓòÉΓòÉΓòÉ
  158.  
  159. /*********************************************************************/
  160. /* address conversion hook for U1 UU2Fido.exe                        */
  161. /*                                                                   */
  162. /* Input:  uucp address of recepient                                 */
  163. /*                                                                   */
  164. /* Output: replacement address                                       */
  165. /*                                                                   */
  166. /*********************************************************************/
  167.  
  168. /* Here's we are loading variable 'inaddr' with value of the first argument */
  169. Parse Arg inaddr
  170.  
  171. /* initialize output to default */
  172. OutString = inaddr
  173.  
  174. /* Put debug info to log file */
  175. log 'Rexx.U2F.Address: InAddr is 'inaddr
  176.  
  177.  
  178. /* return string, removing any blanks on the front or back.   */
  179. Return Strip(OutString)
  180.  
  181. /* end */
  182.  
  183.  
  184. ΓòÉΓòÉΓòÉ 6. Detailed hooks descriptions ΓòÉΓòÉΓòÉ
  185.  
  186. The hooks that are currently available are follow. 
  187.  
  188.  
  189. ΓòÉΓòÉΓòÉ 6.1. Rexx.U2F.Address: UU2Fido UUCP Address Hook ΓòÉΓòÉΓòÉ
  190.  
  191. Description 
  192.  
  193. Example 
  194.  
  195.  
  196. ΓòÉΓòÉΓòÉ 6.1.1. Description of Rexx.U2F.Address ΓòÉΓòÉΓòÉ
  197.  
  198.  Purpose 
  199.            This hook can be used to preprocess (convert) uucp destination 
  200.            address of the letter before passing it to uucp to fido address 
  201.            translator of U1. Note that translating address to user@p#.f#.n#.z# 
  202.            form you can avoid nearly all furher translation of the address by 
  203.            gate. 
  204.  
  205.  Call reason 
  206.            This hook is called for each destination address of letter passed to 
  207.            UU2Fido. 
  208.  
  209.  Parameters 
  210.            The only parameter is destination uucp address. 
  211.  
  212.  Return value 
  213.            This hook must return new uucp address for message or its first 
  214.            parameter if no replacement needed. 
  215.  
  216.  
  217. ΓòÉΓòÉΓòÉ 6.1.2. Sample script for Rexx.U2F.Address ΓòÉΓòÉΓòÉ
  218.  
  219. /**
  220.  * Address conversion hook for UU2Fido.exe. Does nothing.
  221.  *
  222.  * Input:  uucp address of recepient
  223.  *
  224.  * Output: replacement address
  225.  *
  226. **/
  227.  
  228. /* Load variable 'inaddr' with value of the first arg. */
  229. Parse Arg inaddr
  230.  
  231. /* initialize output to default */
  232. OutString = inaddr
  233.  
  234. /* Put debug info to log file */
  235. log 'Rexx.U2F.Address: InAddr is 'inaddr
  236.  
  237. /* return string, removing blanks on the front or back. */
  238. Return Strip(OutString)
  239.  
  240.  
  241. ΓòÉΓòÉΓòÉ 6.2. Rexx.U2F.Pack: UU2Fido UUCP File Compression Hook ΓòÉΓòÉΓòÉ
  242.  
  243. Description 
  244.  
  245. Example 
  246.  
  247.  
  248. ΓòÉΓòÉΓòÉ 6.2.1. Description of Rexx.U2F.Pack ΓòÉΓòÉΓòÉ
  249.  
  250.  Purpose 
  251.            This hook can be used to compress files, attached to the FIDO 
  252.            letters by UU2Fido, with the archiving program you like. 
  253.  
  254.  Call reason 
  255.            This hook is called when letter passed to UU2Fido is large enough to 
  256.            be sent as an attached file instead of simple FIDO message. 
  257.  
  258.  Parameters 
  259.            The first parameter is full name of the file to be compressed, 
  260.            second one points to the directory where compressed file must be 
  261.            created. 
  262.  
  263.  Return value 
  264.            This hook must return name of resulting compressed file. If 
  265.            compression failed, return name of the original file, and, please, 
  266.            leave the file itself intact. If compression is succeded, it is your 
  267.            responcibility to delete original file. 
  268.  
  269.  
  270. ΓòÉΓòÉΓòÉ 6.2.2. Sample script for Rexx.U2F.Pack ΓòÉΓòÉΓòÉ
  271.  
  272. /*****************************************************/
  273. /* attachment packing hook for U1 UU2Fido.exe        */
  274. /*                                                   */
  275. /*                                                   */
  276. /* Input:  unpacked file name (full)                 */
  277. /*         directory to put packed file to           */
  278. /*                                                   */
  279. /* Output: packed file name (full)                   */
  280. /*                                                   */
  281. /*****************************************************/
  282.  
  283. /* get parameters */
  284. Parse Arg unp_name, out_dir
  285.  
  286. /* make sure execution environment is U1's */
  287. address "U1"
  288.  
  289. /* log parameters */
  290. log "Rexx packer ("unp_name", "out_dir")"
  291.  
  292. /* initialize output to default */
  293. OutString = unp_name
  294.  
  295. /* extract filename.extension part form the full name */
  296. p=lastpos('\',unp_name)
  297. if p = 0 then unp_file_ext=unp_name
  298. else unp_file_ext=substr(unp_name,p+1)
  299.  
  300. p=lastpos('/',unp_file_ext)
  301. if \ (p = 0) then unp_file_ext=substr(unp_file_ext,p+1)
  302.  
  303. debug "unp_file_ext: "unp_file_ext
  304.  
  305. /* cut extension off */
  306. p=lastpos('.',unp_file_ext)
  307. if p = 0 then unp_file=unp_file_ext
  308. else unp_file=substr(unp_file_ext,1,p-1)
  309.  
  310. debug "unp_file: "unp_file
  311.  
  312. /* build name of compressed file */
  313. p_name=out_dir||'\'||unp_file||'.zip'
  314.  
  315. debug "p_name: "p_name
  316.  
  317. say "Compressing with zip "unp_name
  318.  
  319. /* execute command */
  320. Address "CMD" 'zip -oj '||p_name||' '||unp_name
  321. if rc = 0 then
  322.     do
  323.     /* Success. Set return value to compressed file name... */
  324.     OutString=p_name
  325.     /* ...and delete uncompressed file */
  326.     call SysDeleteFile unp_name
  327.     end
  328. else
  329.     Error "Unable to zip file, exit code = "||rc
  330.  
  331. /* return string, removing any blanks on the front or back. */
  332. Return Strip(OutString)
  333.  
  334.  
  335. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  336.  
  337. To reach that book open the 'Information' folder on your desktop and 
  338. double-click 'Rexx Information' object in it. 
  339.  
  340.  
  341. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  342.  
  343. usually with an extension of .Rexx