home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / au1_inf.zip / U1_HOOKS.INF (.txt) < prev    next >
OS/2 Help File  |  1995-07-02  |  20KB  |  460 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 different 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 converter. 
  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 in general ΓòÉΓòÉΓòÉ
  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 order 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 unusual 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. Additional REXX operators for GRemote hooks ΓòÉΓòÉΓòÉ
  158.  
  159. U1's remote control unit has it's own extension to the Rexx operator set, which 
  160. is accessible via "GRemote" Rexx environment (you need to use 'ADDRESS 
  161. "GRemote"' to use those operators). 
  162.  
  163.  
  164. ΓòÉΓòÉΓòÉ 5.1. Operator 'GetLetterLine': Reading lines from user letter ΓòÉΓòÉΓòÉ
  165.  
  166.  Purpose 
  167.            Lets you get line from the user's letter text when processing user 
  168.            command. 
  169.  
  170.  Parameters 
  171.            Name of the variable to put line to. 
  172.  
  173.  Notes 
  174.            If no line can be read, variable is not changed. If you pass 
  175.            variable with no value (it is possible to remove value from variable 
  176.            with DROP statement) it can be checked after calling this operator 
  177.            to make sure you have read something. 
  178.  
  179.  Sample 
  180.  
  181.                       /* Read a line into the variable 'input' */
  182.                       /* and display it onscreen */
  183.                       address "gremote" "GetLetterLine" "line"
  184.                       say 'next line: 'line
  185.  
  186.  
  187. ΓòÉΓòÉΓòÉ 5.2. Operator 'PutLetterLine': Writing lines to the reply letter ΓòÉΓòÉΓòÉ
  188.  
  189.  Purpose 
  190.            Lets you put line to the reply letter when processing user command. 
  191.  
  192.  Parameters 
  193.            Text to put. 
  194.  
  195.  Notes 
  196.            None. 
  197.  
  198.  Sample 
  199.  
  200.                       /* Write a line to user */
  201.                       address "gremote" "PutLetterLine" "Hi, Rexx command processor online."
  202.  
  203.  
  204. ΓòÉΓòÉΓòÉ 6. Sample (NULL) script (Rexx.U2F.Address) ΓòÉΓòÉΓòÉ
  205.  
  206. /*********************************************************************/
  207. /* address conversion hook for U1 UU2Fido.exe                        */
  208. /*                                                                   */
  209. /* Input:  uucp address of recipient                                 */
  210. /*                                                                   */
  211. /* Output: replacement address                                       */
  212. /*                                                                   */
  213. /*********************************************************************/
  214.  
  215. /* Here's we are loading variable 'inaddr' with value of the first argument */
  216. Parse Arg inaddr
  217.  
  218. /* initialize output to default */
  219. OutString = inaddr
  220.  
  221. /* Put debug info to log file */
  222. log 'Rexx.U2F.Address: InAddr is 'inaddr
  223.  
  224.  
  225. /* return string, removing any blanks on the front or back.   */
  226. Return Strip(OutString)
  227.  
  228. /* end */
  229.  
  230.  
  231. ΓòÉΓòÉΓòÉ 7. Detailed hooks descriptions ΓòÉΓòÉΓòÉ
  232.  
  233. The hooks that are currently available are follow. 
  234.  
  235.  
  236. ΓòÉΓòÉΓòÉ 7.1. Rexx.U2F.Address: UU2Fido UUCP Address Hook ΓòÉΓòÉΓòÉ
  237.  
  238. Description 
  239.  
  240. Example 
  241.  
  242.  
  243. ΓòÉΓòÉΓòÉ 7.1.1. Description of Rexx.U2F.Address ΓòÉΓòÉΓòÉ
  244.  
  245.  Purpose 
  246.            This hook can be used to preprocess (convert) uucp destination 
  247.            address of the letter before passing it to uucp to fido address 
  248.            translator of U1. Note that translating address to user@p#.f#.n#.z# 
  249.            form you can avoid nearly all further translation of the address by 
  250.            gate. 
  251.  
  252.  Call reason 
  253.            This hook is called for each destination address of letter passed to 
  254.            UU2Fido. 
  255.  
  256.  Parameters 
  257.            The only parameter is destination uucp address. 
  258.  
  259.  Return value 
  260.            This hook must return new uucp address for message or its first 
  261.            parameter if no replacement needed. 
  262.  
  263.  
  264. ΓòÉΓòÉΓòÉ 7.1.2. Sample script for Rexx.U2F.Address ΓòÉΓòÉΓòÉ
  265.  
  266. /**
  267.  * Address conversion hook for UU2Fido.exe. Does nothing.
  268.  *
  269.  * Input:  uucp address of recipient
  270.  *
  271.  * Output: replacement address
  272.  *
  273. **/
  274.  
  275. /* Load variable 'inaddr' with value of the first arg. */
  276. Parse Arg inaddr
  277.  
  278. /* initialize output to default */
  279. OutString = inaddr
  280.  
  281. /* Put debug info to log file */
  282. log 'Rexx.U2F.Address: InAddr is 'inaddr
  283.  
  284. /* return string, removing blanks on the front or back. */
  285. Return Strip(OutString)
  286.  
  287.  
  288. ΓòÉΓòÉΓòÉ 7.2. Rexx.U2F.Pack: UU2Fido UUCP File Compression Hook ΓòÉΓòÉΓòÉ
  289.  
  290. Description 
  291.  
  292. Example 
  293.  
  294.  
  295. ΓòÉΓòÉΓòÉ 7.2.1. Description of Rexx.U2F.Pack ΓòÉΓòÉΓòÉ
  296.  
  297.  Purpose 
  298.            This hook can be used to compress files, attached to the FIDO 
  299.            letters by UU2Fido, with the archiving program you like. 
  300.  
  301.  Call reason 
  302.            This hook is called when letter passed to UU2Fido is large enough to 
  303.            be sent as an attached file instead of simple FIDO message. 
  304.  
  305.  Parameters 
  306.            The first parameter is full name of the file to be compressed, 
  307.            second one points to the directory where compressed file must be 
  308.            created. 
  309.  
  310.  Return value 
  311.            This hook must return name of resulting compressed file. If 
  312.            compression failed, return name of the original file, and, please, 
  313.            leave the file itself intact. If compression is succeded, it is your 
  314.            responsibility to delete original file. 
  315.  
  316.  
  317. ΓòÉΓòÉΓòÉ 7.2.2. Sample script for Rexx.U2F.Pack ΓòÉΓòÉΓòÉ
  318.  
  319. /*****************************************************/
  320. /* attachment packing hook for U1 UU2Fido.exe        */
  321. /*                                                   */
  322. /*                                                   */
  323. /* Input:  unpacked file name (full)                 */
  324. /*         directory to put packed file to           */
  325. /*                                                   */
  326. /* Output: packed file name (full)                   */
  327. /*                                                   */
  328. /*****************************************************/
  329.  
  330. /* get parameters */
  331. Parse Arg unp_name, out_dir
  332.  
  333. /* make sure execution environment is U1's */
  334. address "U1"
  335.  
  336. /* log parameters */
  337. log "Rexx packer ("unp_name", "out_dir")"
  338.  
  339. /* initialize output to default */
  340. OutString = unp_name
  341.  
  342. /* extract filename.extension part form the full name */
  343. p=lastpos('\',unp_name)
  344. if p = 0 then unp_file_ext=unp_name
  345. else unp_file_ext=substr(unp_name,p+1)
  346.  
  347. p=lastpos('/',unp_file_ext)
  348. if \ (p = 0) then unp_file_ext=substr(unp_file_ext,p+1)
  349.  
  350. debug "unp_file_ext: "unp_file_ext
  351.  
  352. /* cut extension off */
  353. p=lastpos('.',unp_file_ext)
  354. if p = 0 then unp_file=unp_file_ext
  355. else unp_file=substr(unp_file_ext,1,p-1)
  356.  
  357. debug "unp_file: "unp_file
  358.  
  359. /* build name of compressed file */
  360. p_name=out_dir||'\'||unp_file||'.zip'
  361.  
  362. debug "p_name: "p_name
  363.  
  364. say "Compressing with zip "unp_name
  365.  
  366. /* execute command */
  367. Address "CMD" 'zip -oj '||p_name||' '||unp_name
  368. if rc = 0 then
  369.         do
  370.         /* Success. Set return value to compressed file name... */
  371.         OutString=p_name
  372.         /* ...and delete uncompressed file */
  373.         call SysDeleteFile unp_name
  374.         end
  375. else
  376.         Error "Unable to zip file, exit code = "||rc
  377.  
  378. /* return string, removing any blanks on the front or back. */
  379. Return Strip(OutString)
  380.  
  381.  
  382. ΓòÉΓòÉΓòÉ 7.3. Rexx.Gremote.Cmd: U1 Remote Control Command Execution Hook ΓòÉΓòÉΓòÉ
  383.  
  384. Description 
  385.  
  386. Example 
  387.  
  388.  
  389. ΓòÉΓòÉΓòÉ 7.3.1. Description of Rexx.Gremote.Cmd ΓòÉΓòÉΓòÉ
  390.  
  391.  Purpose 
  392.            This hook can be used to extend command set of gremote.exe remote 
  393.            control unit. 
  394.  
  395.  Call reason 
  396.            During parsing the letter from user GRemote checks command verb 
  397.            against internal table first, then, if no match found, this hook is 
  398.            called. 
  399.  
  400.  Parameters 
  401.            The first parameter is command verb, second is tail of the command 
  402.            line. 
  403.  
  404.  Return value 
  405.            This hook must return 0 if command verb is correct, nonzero 
  406.            otherwise. 
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ 7.3.2. Sample script for Rexx.Gremote.Cmd ΓòÉΓòÉΓòÉ
  410.  
  411.  
  412. /*****************************************************/
  413. /* Command hook for U1 GRemote.exe                   */
  414. /*                                                   */
  415. /*                                                   */
  416. /* Input:  command, parameters                       */
  417. /*                                                   */
  418. /* Output: 0 if successfull, nonzero otherwise.      */
  419. /*                                                   */
  420. /*****************************************************/
  421.  
  422. /* Get command and parameters */
  423. cmd=arg(1)
  424. par=arg(2)
  425.  
  426. /* GRemote will send user a reply letter. */
  427. /* The following operator adds            */
  428. /* a line of text to that letter          */
  429. call ans "Rexx subsystem online..."
  430. call ans "Processing command "cmd" with parameters "par
  431.  
  432. /* Log what do we do                      */
  433. address "U1" log "Rexx processing command "cmd' with parameters 'par
  434.  
  435. /* Read the following line of user's      */
  436. /* letter to the variable 'line'          */
  437. address "gremote" "GetLetterLine" "line"
  438.  
  439. /* print onscreen what do we got          */
  440. say 'command is 'cmd', parameters: 'par
  441. say 'next line of letter is: 'line
  442.  
  443. return 0
  444.  
  445.  
  446.  
  447. ans: procedure
  448. address "gremote" "PutLetterLine" arg(1)
  449. return
  450.  
  451.  
  452. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  453.  
  454. To reach that book open the 'Information' folder on your desktop and 
  455. double-click 'Rexx Information' object in it. 
  456.  
  457.  
  458. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  459.  
  460. usually with an extension of .Rexx