home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / cmsoriginal / cmswilddoc.txt < prev   
Text File  |  2020-01-01  |  5KB  |  169 lines
  1. Revised: 2/8/83                                                 WILD SUBROUTINE
  2.  
  3.  
  4. 1. Introduction
  5.  
  6.   The  WILD  subroutine  is  an  assembler  language  subroutine  which is PL/I
  7. callable as well as assembler callable.  It compares two varying length strings
  8. with wild card matching.
  9.  
  10. 2. CMS Command Syntax and Options
  11.  
  12.   The subroutine may be declared either with two or three parameters from  PL/I
  13. as follows:
  14.  
  15.     DECLARE WILD ENTRY(CHAR(*) VAR,CHAR(*) VAR[,CHAR(2)])
  16.         EXTERNAL OPTIONS(ASSEMBLER,INTER,RETCODE);
  17.  
  18.   and called as follows:
  19.  
  20.     CALL WILD(pattern,source[,wildcards]);
  21.  
  22. where  "pattern"  and  "source"  are  character(*)  varying  and "wildcards" is
  23. character(2). "pattern" and "source" need not be the same  length.    "pattern"
  24. represents  the pattern string, whereas "source" is the string to be tested for
  25. matching the patten. "wildcard", if  specified,  represents  the  two  wildcard
  26. characters. The first of the two characters is a symbol which may appear in the
  27. pattern  string  but  not  the source string which will match any number of any
  28. characters (SNOBOL's ARB pattern). It is the calling  program's  responsibility
  29. to  ensure  that  the  first  wildcard  character does not appear in the source
  30. string.  The second wildcard character which may appear in the  pattern  and/or
  31. the  source  string  will  match  any  single  character  in  the source string
  32. (SNOBOL's LEN(1)). If only two strings are passed, then the wildcard characters
  33. default to "*" for ARB and "%" for LEN(1).
  34.  
  35.   To call WILD from assembler, use the standard OS calling  conventions.    The
  36. format of the source and pattern strings is as follows:
  37.  
  38.                  +----------+--------------------+
  39.                  |          |                    |
  40.                  +----------+--------------------+
  41.                     length          text
  42.  
  43.   where the length field is a binary halfword containing the length of the text
  44. field.  The  wildcard string is simply a two byte string (CL2).  If no wildcard
  45. string is to be passed to WILD, then the first byte of the second word  of  the
  46. parameter address block (PAB) must be X'80'.
  47.  
  48.   If  the  strings match, then WILD will set a return code of 0 whereas if they
  49. don't match the return code will be set to 8.  From  PL/I  this  value  may  be
  50. examined  through the PLIRETV builtin function, from assembler register 15 will
  51. contain the return code.
  52.  
  53.   Note:  PLIRETV should be declared as follows:
  54.  
  55.     DECLARE PLIRETV BUILTIN;
  56.                       CUCCA User Services Technical Note                    [1]
  57. Revised: 2/8/83                                                 WILD SUBROUTINE
  58.  
  59.  
  60. and  then used as any normal builtin function having no arguements (see example
  61. below).
  62.  
  63. 3. Examples under CMS
  64.  
  65.   This is an example of calling WILD from  a  PL/I  program  passing  it  three
  66. parameters:
  67.  
  68.     /* S1 IS THE PATTERN AND S2 IS THE SOURCE */
  69.     DECLARE (S1,S2) CHAR(72) VARYING;
  70.     /*  $ IS ARB AND  & IS LEN(1)   */
  71.     DECLARE WILDCHARS CHAR(2) STATIC INITIAL('$&');
  72.     DECLARE WILD ENTRY(CHAR(*) VAR,CHAR(*) VAR,CHAR(2))
  73.          EXTERNAL OPTIONS(ASSEMBLER,RETCODE,INTER);
  74.     DECLARE PLIRETV BUILTIN;
  75.          .
  76.          .
  77.          .
  78.     CALL WILD(S1,S2,WILDCHARS);
  79.     IF PLIRETV=8 THEN GOTO NOMATCH;
  80.                  ELSE GOTO MATCH;
  81.  
  82.  
  83.  
  84.   This  example  illustrates  calling  WILD  from  assembler  using the default
  85. wildcard characters:
  86.  
  87.             L       15,=V(WILD)     POINT AT SUBROUTINE
  88.             LA      1,PAB           POINT AT PAB TO PASS
  89.             BALR    14,15           DO CALL
  90.     * THE RETURN IS TO HERE
  91.             LTR     15,15           IS THE RETURN CODE 0?
  92.             BZ      MATCH           IF SO THEN GOTO MATCH
  93.             B       NOMATCH         OTHERWISE GOTO NOMTACH
  94.              .
  95.              .
  96.              .
  97.     PAB     DS      0F           FULLWORD ALIGN THE PAB
  98.             DC      A(PATTERN)   ADDRESS OF PATTERN STRING
  99.             DC      X'80'        FLAG INDICATING ONLY 2 PARMS
  100.             DC      AL3(SOURCE)  ADDRESS OF SOURCE STRING
  101.              .
  102.              .
  103.              .
  104.     PATTERN DS      H           FILL IN LENGTH OF PATTERN
  105.             DS      CL80        ANY LENGTH FOR PATTERN STRING
  106.     SOURCE  DS      H           FILL IN LENGTH OF SOURCE
  107.             DS      CL90        ANY LENGTH FOR SOURCE STRING
  108.  
  109.  
  110.  
  111.  
  112.                       CUCCA User Services Technical Note                    [2]
  113. Revised: 2/8/83                                                 WILD SUBROUTINE
  114.  
  115.  
  116. 4. VS1 JCL
  117.  
  118.                                 NOT APPLICABLE
  119.  
  120. 5. Examples under VS1
  121.  
  122.                                 NOT APPLICABLE
  123.  
  124. 6. Additional Information
  125.  
  126.   WILD runs extremely quickly and may be freely used to compare two strings.
  127.  
  128. 7. Reference
  129.  
  130.                                 NOT APPLICABLE
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.                       CUCCA User Services Technical Note                    [3]
  169.