home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 303.lha / AssemTools / Include / include.doc < prev    next >
Text File  |  1980-12-03  |  29KB  |  1,486 lines
  1.  
  2.     DOSLIB.I * Metacc Include File
  3.          Version 1.21
  4.             Date 27.06.89
  5.  
  6.  
  7.     EXECLIB.I * Metacc Include File
  8.         Version 1.08
  9.           Date 12.06.1989
  10.  
  11.  
  12.     GFXLIB.I * Metacc Include File
  13.         Version 1.01
  14.            Date 15.06.89
  15.  
  16.  
  17.     INTLIB.I * Metacc Include File
  18.         Version 1.063
  19.             Date 25.06.89
  20.  
  21.  
  22.     JOYSTICK.I * Metacc Include File
  23.         Version 1.3
  24.           Date 04.03.1989
  25.  
  26.  
  27.     MATH.I * Metacc Include File
  28.         Version 1.4
  29.            Date 21.06.89
  30.  
  31.  
  32.     NUMERIC.I * Metacc Include File
  33.         Version 1.42
  34.            Date 01.07.89
  35.  
  36.  
  37.     STRING.I  *  Metacc Include File
  38.         Version 1.763
  39.         Date 22.06.89
  40.  
  41.  
  42.     ---
  43.     ABS
  44.     ---
  45.  
  46.    abs        (abs(x))
  47.    in:        d0: integer;
  48.    call:    mathlib abs;
  49.    out:        d0: positive integer;
  50.  
  51.  
  52.     ------
  53.     ADDDIR
  54.     ------
  55.  
  56.    adddir    (move to directory)
  57.    in:        a0=dir_name;
  58.    call:    doslib    adddir;
  59.    out:        a0=dir_name; d0=success (0=fail);
  60.    notes:    /locks the new, unlocks the old/;
  61.  
  62.  
  63.     -------
  64.     ADDPATH
  65.     -------
  66.  
  67.    addpath    (add a dirname to path)
  68.    in:        a0=dir_name; a1=pathname_string;
  69.    call:    doslib    addpath;
  70.    out:        a0=dir_name; a1=pathname_string;
  71.    notes:    /a masterpiece - handles also parent-dirs,/
  72.           /device names, rootdirs, subdirectories and yet/
  73.           /all these together/
  74.          /strlib must be included/;
  75.  
  76.  
  77.     --------
  78.     ADDSLASH
  79.     --------
  80.  
  81.    addslash    (add slash into end of string if not / or :)
  82.    in:        a0=*string;
  83.    call:    strlib addslash;
  84.    out:        a0=*(NULL);
  85.  
  86.  
  87.     -----
  88.     ALLOC
  89.     -----
  90.  
  91.    alloc    (allocate memory and argue if not got)
  92.    in:        d0=bytesize, d1=requirements;
  93.    call:    doslib    alloc;
  94.    out:        a0=d0=location;
  95.  
  96.  
  97.     -----
  98.     ALLOC
  99.     -----
  100.  
  101.    alloc    (allocate memory)
  102.    in:        d0=bytesize; d1=requirements;
  103.    call:    execlib    alloc;
  104.    out:        a0=d0=*memory;
  105.    notes:    /allocates 4 bytes more and saves/
  106.          /the length, like util.i's/
  107.  
  108.  
  109.     -------
  110.     ALLOCGG
  111.     -------
  112.  
  113.    allocgg    (allocate and create a gadget structure chain)
  114.    in:        a0=*gadgetdata; a1=*strgad_bufr_base;
  115.    call:    intlib    allocgg;
  116.    out:        d0=a0=*firstgadget; /use execlib->free to free/
  117.    notes:    The gadgetdata list may contain elements
  118.          of the following form:
  119.           type.w, x1.w, y1.w, sx.w, sy.w, userdata.l,
  120.           specl.w
  121.          followed by "specl" bytes of additional data.
  122.          See "info:sample.gad" for examples.
  123.  
  124.  
  125.     ----
  126.     BADD
  127.     ----
  128.  
  129.    badd        (add bcd)
  130.    in:        a0, d0: bcd; a1, d1: bcd;  {a0=a0+a1}
  131.    call:    mathlib    badd;
  132.    notes:    d0 is UWORD length of bcd a0 (in bytes),
  133.            d1 is the same for a1. Action taken when
  134.            either of the lengths is zero is undefined.
  135.            The pointers a0, a1 point to the first (most
  136.            significant) byte of the signed bcd.
  137.  
  138.  
  139.     ----
  140.     BCHK
  141.     ----
  142.  
  143.    bchk        (check bcd)
  144.    in:        a0, d0: bcd;  {check if valid bcd value}
  145.    call:    mathlib    bchk;
  146.    out:        d0: result; {if 0, value is OK}
  147.    notes:    See "badd"
  148.  
  149.  
  150.     ----
  151.     BCLR
  152.     ----
  153.  
  154.    bclr        (clear bcd)
  155.    in:        a0, d0: bcd;  {a0=0}
  156.    call:    mathlib    bclr;
  157.    notes:    See "badd"
  158.  
  159.  
  160.     ----
  161.     BCMP
  162.     ----
  163.  
  164.    bcmp        (compare bcd)
  165.    in:        a0, d0: bcd1; a1, d1: bcd2;  {cmp a1,a0}
  166.    call:    mathlib    cbmp;
  167.    out:        d0: sign_of_result = in {-1, 0, 1};
  168.          p.flags = set_according_to_comparison;
  169.    notes:    See "badd"
  170.  
  171.  
  172.     ----
  173.     BEEP
  174.     ----
  175.  
  176.    beep        (beep)
  177.    in:        d0=(uword) period, d1=(uword) cycles;
  178.    call:    execlib    beep;
  179.    out:        d0=success; /0 = error/
  180.    notes:    /"cycles" defines the length of the beep/
  181.            /if d0 is -1, default values are used for
  182.            both the period (1050) and cycles (300)/
  183.  
  184.  
  185.     ------
  186.     BLKCPY
  187.     ------
  188.  
  189.    blkcpy    (string copy /blank or comma terminated/)
  190.    in:        a0=*source_string; a1=*target_string;
  191.    call:    strlib blkcpy;
  192.    out:        a0=*rest_of_string=*(BLANK or NULL);
  193.            a1=*after_target_string=(*NULL)+1;
  194.    notes:    /the target string will be null-terminated/
  195.            /whilst the source string terminates/
  196.            /with either blank, comma or null/
  197.          /quotes "" enbrace strings with blanks/
  198.          /"*" (in quotes) as in the CLI cmds/
  199.  
  200.  
  201.     -------
  202.     BLKNCPY
  203.     -------
  204.  
  205.    blkncpy    (string copy /length-limited blkcpy/)
  206.    in:        a0=*source_string; a1=*target_string; d0=max_length;
  207.    call:    strlib blkncpy
  208.    out:        a0=*rest_of_string=*(BLANK or NULL);
  209.            a1=*after_target_string=(*NULL)+1;
  210.            d0=num_of_chars_left_in_buffer;
  211.    notes:    /*n, *N = newline (10)/
  212.            /*e, *E = esc (27)/
  213.            /*t, *T = tab (9)/
  214.  
  215.  
  216.     -----
  217.     BMOVE
  218.     -----
  219.  
  220.    bmove    (move and extend bcd)
  221.    in:        a0, d0: bcd; a1, d1: bcd;  {a1=a0}
  222.    call:    mathlib    bmove;
  223.    notes:    See "badd";
  224.          If the bcd a1 is longer than a0, the
  225.          value is sign-extended to full length.
  226.  
  227.  
  228.     ----
  229.     BNEG
  230.     ----
  231.  
  232.    bneg        (negate bcd)
  233.    in:        a0, d0: bcd;  {a0=-a0}
  234.    call:    mathlib    bneg;
  235.    notes:    See "badd"
  236.  
  237.  
  238.     ----
  239.     BSUB
  240.     ----
  241.  
  242.    bsub        (subtract bcd)
  243.    in:        a0, d0: bcd; a1, d1: bcd;  {a0=a0-a1}
  244.    call:    mathlib    bsub;
  245.    notes:    See "badd"
  246.  
  247.  
  248.     ----
  249.     BTST
  250.     ----
  251.  
  252.    btst        (test bcd)
  253.    in:        a0, d0: bcd;  {a0?}
  254.    call:    mathlib    btst;
  255.    out:        d0: integer in {-1, 0, 1};
  256.    notes:    See "badd"
  257.  
  258.  
  259.     -------
  260.     CHECK10
  261.     -------
  262.  
  263.    check10    (check whether decimal (base10) value follows)
  264.    in:        a0=*ptr;
  265.    call:    numlib check10;
  266.    out:        p.z=result (NE if no value)
  267.    notes:    /the value may be terminated by any character
  268.          less than '@' (64) except a decimal digit/
  269.          /if any other character terminates it, it is
  270.          not considered to be a number/
  271.  
  272.  
  273.     -------
  274.     CHECK16
  275.     -------
  276.  
  277.    check16    (check whether hexadec (base16) value follows)
  278.    in:        a0=*ptr;
  279.    call:    numlib check16;
  280.    out:        p.z=result (NE if no value)
  281.    notes:    /the value may be terminated by any character
  282.          less than '@' (64) except a hexadecimal digit/
  283.          /if any other character terminates it, it is
  284.          not considered to be a number/
  285.  
  286.  
  287.     --------
  288.     CHKSLASH
  289.     --------
  290.  
  291.    chkslash    (check if a this string ends with a / or :)
  292.    in:        a0=*string;
  293.    call:    strlib chkslash;
  294.    out:        p.z=result /Z is set if no "/" or ":"/;
  295.  
  296.  
  297.     ---------
  298.     CHRCURSOR
  299.     ---------
  300.  
  301.    chrcursor    (set and read current cursor position)
  302.    in:        d0, d1=column, row; a1=*chrout;
  303.    call:    intlib    chrcursor;
  304.    out:        d0, d1=oldcolumn, oldrow;
  305.  
  306.  
  307.     ------
  308.     CHROUT
  309.     ------
  310.  
  311.    chrout    (output text into a chrout)
  312.    in:        a0=*string; a1=*chrout;
  313.    call:    intlib    chrout;
  314.    notes:    Control codes are:
  315.          8   BS   Backspace. Cursor left
  316.          9   TAB  Tabulator (size 8 characters)
  317.          10  LF   Line feed
  318.          11  VT   Vertical tab. Cursor up
  319.          12  FF   Form feed (clearscreen)
  320.          13  CR   Carriage return
  321.          14  SO   Cursor on
  322.          15  SI   Cursor off
  323.          16  DLE  Scroll up one line
  324.          17  DC1  Scroll down one line
  325.          20  DC4  Clear to end of line
  326.          21  NAK  Insert character
  327.          22  SYN  Delete line at cursor
  328.          23  ETB  Insert line at cursor
  329.          24  CAN  Clear line at cursor and end of screen
  330.          25  EM   Cursor to nethermost line
  331.          26  SUB  Cursor home
  332.          28  FS   Cursor up. Scroll if out
  333.          29  GS   Cursor down. Scroll if out
  334.          30  RS   Cursor left
  335.          31  US   Cursor right
  336.          127 DEL  Delete character to right
  337.  
  338.  
  339.     -------
  340.     CMDNAME
  341.     -------
  342.  
  343.    cmdname    (get the current command name)
  344.    in:        a0=*buffer;
  345.    call:    doslib    cmdname;
  346.    out:        a0=*end_of_name==*NULL;
  347.  
  348.  
  349.     --------
  350.     CREATEIO
  351.     --------
  352.  
  353.    createio    (creates an IORequest structure)
  354.    in:        a0=*messageport; d0=size;
  355.    call:    execlib    createio;
  356.    out:        a0=d0=*iorequest;
  357.    trashed:    a1, d1;
  358.  
  359.  
  360.     ----------
  361.     CREATEPORT
  362.     ----------
  363.  
  364.    createport    (creates a message port)
  365.    in:        a0=*name; d0=sizeof;
  366.    call:    execlib createport;
  367.    out:        a0=d0=*port;
  368.    trashed:    a1, d1;
  369.  
  370.  
  371.     --------
  372.     DELETEIO
  373.     --------
  374.  
  375.    deleteio    (deletes an IORequest structure)
  376.    in:        a0=*iorequest;
  377.    call:    execlib    deleteio
  378.    trashed:    a0-a1, d0-d1;
  379.  
  380.  
  381.     ----------
  382.     DELETEPORT
  383.     ----------
  384.  
  385.    deleteport    (deletes a message port)
  386.    in:        a0=*port;
  387.    call:    execlib    deleteport;
  388.    trashed:    a0-a1, d0-d1;
  389.  
  390.  
  391.     -----
  392.     DIV10
  393.     -----
  394.  
  395.    div10    (divide long-integer by 10 /unsigned/)
  396.    in:        d0=value;
  397.    call:    numlib div10;
  398.    out:        d0=value DIV 10; d1=(UWORD) value MOD 10;
  399.  
  400.  
  401.     ----
  402.     DIVS
  403.     ----
  404.  
  405.    divs        (divide / 32/32->32 bits, signed /)
  406.    in:        d0, d1: integer;  { d0/d1 }
  407.    call:    mathlib divs;
  408.    out:        d0: d0 div d1;
  409.            d1: d0 mod d1;
  410.  
  411.  
  412.     ----
  413.     DIVU
  414.     ----
  415.  
  416.    divu        (divide / 32/32->32 bits, unsigned /)
  417.    in:        d0, d1: integer;  { d0/d1 }
  418.    call:    mathlib divu;
  419.    out:        d0: d0 div d1;
  420.            d1: d0 mod d1;
  421.  
  422.  
  423.     -------
  424.     DPY_ERR
  425.     -------
  426.  
  427.    dpy_err    (display a formatted error message)
  428.    in:        a0=*format_string; d0..d7=parameters;
  429.    call:    doslib    dpy_err;
  430.    notes:    /" - error code %d\n" will be automatically
  431.          added before printing/
  432.  
  433.  
  434.     -------
  435.     DPY_MSG
  436.     -------
  437.  
  438.    dpy_msg    (display a formatted message)
  439.    in:        a0=*format_string; d0..d7=parameters;
  440.    call:    doslib    dpy_msg;
  441.  
  442.  
  443.     ---------
  444.     DRAWARRAY
  445.     ---------
  446.  
  447.    drawarray    (draw from a table of commands)
  448.    in:        d0=x0, d1=y0; a0=*array; a1=rport;
  449.    call:    gfxlib    drawarray;
  450.    notes:    Possible commands are (given in Ascii):
  451.              Mx,y    Move drawing pen to (x,y)
  452.              Dx,y    Draw line to (x,y)
  453.              Rx,y    Draw rectangle to (x,y)
  454.              Tl,t  Write text "t" of length l using
  455.              last x,y as centre
  456.            Fx,y    Fill rectangle to (x,y)
  457.              Ax    Set APen
  458.              'NUL'    End of array (a NULL char.)
  459.            where x and y given as signed decimal
  460.          (base 10) integers (coordinates relative
  461.          to (x0,y0)).
  462.  
  463.  
  464.     --------
  465.     DRAWRECT
  466.     --------
  467.  
  468.    drawrect    (draw a rectangle)
  469.    in:        d0=x1, d1=y1, d2=x2, d3=y2; a1=rport;
  470.    call:    gfxlib    drawrect;
  471.    notes:    /the drawing pen will be left into/
  472.            /position (x1,y1)./
  473.  
  474.  
  475.     -----
  476.     ERROR
  477.     -----
  478.  
  479.    error    (set/read the dos error return code)
  480.    in:        d0=error;
  481.    call:    doslib    error;
  482.    out:        d0=old_error;
  483.          p.c=failed /C is set if not a CLI process/
  484.  
  485.  
  486.     --------
  487.     ERR_LOCK
  488.     --------
  489.  
  490.    err_lock    (display "unable to get information")
  491.    in:        a0=*name;
  492.    call:    doslib    err_lock;
  493.  
  494.  
  495.     -------
  496.     ERR_MEM
  497.     -------
  498.  
  499.    err_mem    (display "unable to allocate memory")
  500.    in:        d0=*size;
  501.    call:    doslib    err_lock;
  502.  
  503.  
  504.     --------
  505.     ERR_READ
  506.     --------
  507.  
  508.    err_read    (display "error reading file")
  509.    in:        a0=*name;
  510.    call:    doslib    err_lock;
  511.  
  512.  
  513.     -----
  514.     EXTBL
  515.     -----
  516.  
  517.    extbl    (sign extend byte to long)
  518.    in:        d0: byte;
  519.    call:    mathlib extbl;
  520.    out:        d0: long;
  521.  
  522.  
  523.     --------
  524.     EXTFNAME
  525.     --------
  526.  
  527.    extfname    (extract file name from a valid path+filename)
  528.    in:        a0=*string;
  529.    call:    strlib extfname;
  530.    out:        a0=*filename;
  531.    notes:    if no filename is present, the last directoryname
  532.            must be followed by slash (/).
  533.  
  534.  
  535.     ----------
  536.     FILELENGTH
  537.     ----------
  538.  
  539.    filelength    (find out length of a file)
  540.    in:        a0=file_name;
  541.    call:    doslib    filelength;
  542.    out:        d0=file_length; /-1 = error/
  543.  
  544.  
  545.     ------
  546.     FINDGG
  547.     ------
  548.  
  549.    findgg    (find a gadget by UserData)
  550.    in:        a0=*firstgadget; d0=userdata;
  551.    call:    intlib    findgg;
  552.    out:        a0=*gadget; /==0 if not found/
  553.  
  554.  
  555.     -------
  556.     FINDGGW
  557.     -------
  558.  
  559.    findggw    (find a gadget by a halve of UserData)
  560.    in:        a0=*firstgadget; d0=(uword) userdata;
  561.    call:    intlib    findggw;
  562.    out:        a0=*gadget; /==0 if not found/
  563.  
  564.  
  565.     -------
  566.     FINDNTH
  567.     -------
  568.  
  569.    findnth    (find string from list /null terminated/)
  570.    in:        a0=*string; a1=*list;
  571.    call:    strlib findnth;
  572.    out:        d0=count;
  573.    notes:    /0 stands for the first string, -1 for error/
  574.          /the list should be terminated by an empty/
  575.          /string./
  576.  
  577.  
  578.     --------
  579.     FINDPROC
  580.     --------
  581.  
  582.    findproc    (find a cli process by the number)
  583.    in:        d0=number;
  584.    call:    doslib    findproc;
  585.    out:        a0=d0=*task; /NULL if error/
  586.  
  587.  
  588.     -------
  589.     FINDTOK
  590.     -------
  591.  
  592.    findtok    (find token from list /case-insensitive/)
  593.    in:        a0=*token; a1=*list;
  594.    call:    strlib findtok;
  595.    out:        d0=count; /-1 =^ not found/
  596.    notes:    /see tokcmp/
  597.  
  598.  
  599.     -------
  600.     FMTDATE
  601.     -------
  602.  
  603.    fmtdate    (format a date)
  604.    in:        a0=*datestamp; a1=*output_buffer;
  605.          a2=*format, a3=*parameters;
  606.    call:    doslib    fmtdate;
  607.    out:        a1=*NULL;
  608.    notes:    /"format" contains an ordinary "sformat" string
  609.          defining how the parameters are formatted/
  610.          /"parameters" is a character queue containing
  611.          the following characters:
  612.          y - number of year    Y - the last two digits
  613.          m - number of month    M - name of month
  614.          d - day-of-month    D - name of day-of-week
  615.          The characters M and D require a %s declaration
  616.          in the "format", the others a (word) %d./
  617.  
  618.  
  619.     ------------
  620.     FOLLOWTHREAD
  621.     ------------
  622.  
  623.    followthread    (follow the directory thread to root)
  624.    in:        d1=lock; a0=*name_buffer, d0=buf_length;
  625.    call:    doslib    followthread;
  626.    out:        p.c=error; (c=1 if failed)
  627.    notes:    /the lock is not unlock()ed during process/
  628.  
  629.  
  630.     ------
  631.     FORMAT
  632.     ------
  633.  
  634.    format    (format a string)
  635.    in:        a0=*format_string;
  636.            a1=*output_buffer;
  637.            a2=*data_stream;
  638.    call:    execlib    format;
  639.    out:        a0=a1=*output_buffer_end==*(NULL);
  640.    notes:    /data_stream may contain either words,
  641.            longwords, or both. The 'l' specifiers
  642.            must be used accordingly./
  643.            /The format for the item specifier is:
  644.              %-0xxx.yyylc
  645.            where
  646.              '-' , if specified, left-aligns the value,
  647.              '0' right-aligns the value filling the
  648.                  opening space with zeros,
  649.              'xxx' and 'yyy' are the field widths,
  650.              'l' is a longword specifer, and
  651.              'c' is one of the following:
  652.                 's': string output, pointer in data stream
  653.                      pointer is supposed to be 'l' even if
  654.                      the specifier were not used.
  655.                 'c': single character output
  656.                 'd': decimal value output
  657.                 'x': hexadecimal value output/
  658.  
  659.  
  660.     ----
  661.     FREE
  662.     ----
  663.  
  664.    free        (free memory)
  665.    in:        a0=*memory;
  666.    call:    execlib    free;
  667.    notes:    /frees that being allocated by alloc/
  668.            /doesn't care even if the pointer be/
  669.            /NULL - just doesn't free it/
  670.  
  671.  
  672.     -----
  673.     GET10
  674.     -----
  675.  
  676.    get10    (string10 to integer /signed/)
  677.    in:        a0=*string;
  678.    call:    numlib get10;
  679.    out:        a0=*endofvalue; d0=integer;
  680.            p.c=error_exit; /if no value present/
  681.  
  682.  
  683.     -----
  684.     GET16
  685.     -----
  686.  
  687.    get16    (string16 to integer /signed/)
  688.    in:        a0=*string;
  689.    call:    numlib get16;
  690.    out:        a0=*endofstring; d0=integer;
  691.          p.c=error_exit; /if no value present/
  692.  
  693.  
  694.     -------
  695.     GETBCPL
  696.     -------
  697.  
  698.    getbcpl    (convert FROM BCPL string)
  699.    in:        a0=*bcpl_string; a1=*string;
  700.    call:    strlib getbcpl;
  701.    out:        a1=*NULL;
  702.    notes:    /the pointers are both APTRs and NOT BPTRs/
  703.  
  704.  
  705.     ------
  706.     GETCLI
  707.     ------
  708.  
  709.    getcli    (get the address of CLIStruct)
  710.    call:    doslib    getcli;
  711.    out:        a0=*clistruct; /0 if not a cli process/
  712.    notes:    /flags set according to the result/
  713.  
  714.  
  715.     -------
  716.     GETDATE
  717.     -------
  718.  
  719.    getdate    (convert a datestamp)
  720.    in:        a0=*datestamp;
  721.    call:    doslib    getdate;
  722.    out:        d0=year, d1=month /1..12 Jan..Dec/,
  723.          d2=day_of_month, d3=day_of_week /0..6 Mon..Fri/;
  724.  
  725.  
  726.     --------
  727.     GETIDCMP
  728.     --------
  729.  
  730.    getidcmp    (get a standard idcmp message)
  731.    in:        a0=*window; d0=flag /=0: wait, <>0 do not wait/;
  732.    call:    intlib    getidcmp;
  733.    out:        d0=class, d1=code, d2=qualifier;
  734.            a0=iaddress, d3,d4=mousex,mousey;
  735.  
  736.  
  737.     --------
  738.     GETIWORD
  739.     --------
  740.  
  741.    getiword    (get integer string /double longword/)
  742.    in:        a0=*string;
  743.    call:    strlib getiword;
  744.    out:        a0=*newstring; d1:d0=string;
  745.    notes:    /included characters are:/
  746.            /a-z, A-Z for first character/
  747.            /a-z, A-Z, 0-9 for other characters/
  748.            /no more than 8 characters will be fetched/
  749.  
  750.  
  751.     ---------
  752.     GETIWORDU
  753.     ---------
  754.  
  755.    getiwordu    (get integer string and ucase /double longword/)
  756.    in:        a0=*string;
  757.    call:    strlib getiwordu;
  758.    out:        a0=*newstring; d1:d0=string;
  759.    notes:    /see getiword/
  760.  
  761.  
  762.     ----------
  763.     GETRAWDATA
  764.     ----------
  765.  
  766.    getrawdata    (get raw data string)
  767.    in:        a0=*from, a1=*to;
  768.    call:    strlib getrawdata;
  769.    out:        a0=*from_rest, a1=*to_end, d0=length_of_TO;
  770.    notes:    /The 'raw data' may include one or more
  771.             of the following elements, separated by
  772.             commas, ending with a blank or NULL:
  773.               "blubblub"    8-bit ascii data
  774.               123 or 123.b    8-bit decimal data
  775.               $ab or $ab.b    8-bit hexadec data
  776.               1234.w    16-bit decimal data
  777.               $12ab.w    16-bit hexadec data
  778.               123456.l    32-bit decimal data
  779.               $12ab56.l    32-bit hexadec data
  780.             ** Requires 'numlib' (getval)
  781.            /
  782.  
  783.  
  784.     -------
  785.     GETTOKW
  786.     -------
  787.  
  788.    gettokw    (get a token word)
  789.    in:        a0=txtptr; a1=*buffer; d0=(UWORD)buffer_length;
  790.    call:    strlib gettokw;
  791.    out:        a0=txtptr /updated/ ; a1=*buffer;
  792.            p.c=error; /c=1 if buffer overflow/
  793.    notes:    /a token word:/
  794.            /- begins with a-z|A-Z|.|_/
  795.            /- other chrs are a-z|A-Z|0-9|.|_/
  796.            /- must be at least 1 char. long/
  797.  
  798.  
  799.     ------
  800.     GETVAL
  801.     ------
  802.  
  803.    getval    (string to integer /signed/)
  804.    in:        a0=*string;
  805.    call:    numlib getval;
  806.    out:        a0=*endofstring; d0=integer;
  807.            p.c=error_exit; /if no value present/
  808.    notes:    /base 16 values have prefix $/
  809.            /base 10 values have no prefix or prefix +/
  810.  
  811.  
  812.     --------
  813.     GGBORDER
  814.     --------
  815.  
  816.    ggborder    (draw simple border to gadgets)
  817.    in:        a0=*gadgetdata; a1=*rport;
  818.    call:    intlib    ggborder;
  819.  
  820.  
  821.     ---
  822.     HYP
  823.     ---
  824.  
  825.    hyp        (sqrt(x²+y²))
  826.    in:        d0, d1: integer;
  827.    call:    mathlib    hyp;
  828.    out:        d0: integer;
  829.    notes:    See "sqrt"
  830.  
  831.  
  832.     -----
  833.     INFOS
  834.     -----
  835.  
  836.    infos    (type info/finfo/sinfo texts)
  837.    in:        a0=*cmdlin, a1=*usage, a2=*finfo_info;
  838.    call:    doslib    infos;
  839.    out:        d0=flag /==0 if nothing done/
  840.    notes:    /at the address a2 is give the "finfotx",
  841.          then NULL, then "infotxt" and another null./
  842.          /The string at a1 does not contain the word
  843.          "usage" or the command name./
  844.  
  845.  
  846.     ----------
  847.     INITCHROUT
  848.     ----------
  849.  
  850.    initchrout    (init a chrout structure)
  851.    in:        a0=*window; a1=*chrout;
  852.    call:    intlib    initchrout;
  853.  
  854.  
  855.     -----
  856.     IOERR
  857.     -----
  858.  
  859.    ioerr    (get IoErr code and convert to string)
  860.    in:        a0=place_for_string;
  861.    call:    doslib    ioerr;
  862.    out:        a0=*(NULL); d0=ioerr;
  863.    notes:    /the format is as/
  864.          /sprintf(" - Error code %i",IoErr());/
  865.          /numlib, handler must be included/;
  866.  
  867.  
  868.     -------
  869.     ISALPHA
  870.     -------
  871.  
  872.    isalpha    (check if alpha /a-z, A-Z/)
  873.    in:        d0=char;
  874.    call:    strlib isalpha;
  875.    out:        p=(flags) result; /eq if true/
  876.  
  877.  
  878.     ----------
  879.     ISALPHANUM
  880.     ----------
  881.  
  882.    isalphanum    (check if alphanumeric /a-z, A-Z, 0-9/)
  883.    in:        d0=char;
  884.    call:    strlib isalphanum;
  885.    out:        p=(flags) result; /eq if true/
  886.  
  887.  
  888.     -------
  889.     ISBLANK
  890.     -------
  891.  
  892.    isblank    (check if blank /32, 9, 10/)
  893.    in:        d0=char;
  894.    call:    strlib isblank;
  895.    out:        p.z=(boolean) result; /eq if blank/
  896.  
  897.  
  898.     ---------
  899.     ISDIGIT10
  900.     ---------
  901.  
  902.    isdigit10    (check if base10 digit)
  903.    in:        d0=character;
  904.    call:    numlib isdigit10;
  905.    out:        p=(flags) result /eq if true/;
  906.  
  907.  
  908.     ---------
  909.     ISDIGIT16
  910.     ---------
  911.  
  912.    isdigit16    (check if base16 digit /non-case-sensitive/)
  913.    in:        d0=character;
  914.    call:    numlib isdigit10;
  915.    out:        p=(flags) result /eq if true/;
  916.  
  917.  
  918.     -----
  919.     ISEND
  920.     -----
  921.  
  922.    isend    (skip blanks - end of command line? (0/";"))
  923.    in:        a0=ptr;
  924.    call:    doslib    isend;
  925.    out:        a0=ptr;
  926.    notes:    /strlib must be included/;
  927.  
  928.  
  929.     ---------
  930.     ISNUMERIC
  931.     ---------
  932.  
  933.    isnumeric    (check if numeric /0-9/)
  934.    in:        d0=char;
  935.    call:    strlib isnumeric;
  936.    out:        p=(flags) result; /eq if true/
  937.  
  938.  
  939.     -------
  940.     LISTLEN
  941.     -------
  942.  
  943.    listlen    (measure length of a string list)
  944.    in:        a0=*string_list;
  945.    call:    strlib listlen;
  946.    out:        d0=number_of_bytes; d1=number_of_strings;
  947.    notes:    /d0 is the number of bytes occupied by/
  948.            /the list, including the end nulls/
  949.            /d1 is the number of the string in the list/
  950.  
  951.  
  952.     ------
  953.     LOCASE
  954.     ------
  955.  
  956.    locase    (convert character to lower case /byte/)
  957.    in:        d0=char;
  958.    call:    strlib locase;
  959.    out:        d0=newchar;
  960.  
  961.  
  962.     -------
  963.     LZPUT10
  964.     -------
  965.  
  966.    lzput10    (short integer to string10 /unsigned, incl. leading zeroes/)
  967.    in:        a0=*string; d0=short_integer;
  968.    call:    numlib lzput10;
  969.    out:        a0=*(NULL);
  970.    notes:    /output string always 5 characters + NULL/
  971.  
  972.  
  973.     ----
  974.     MULS
  975.     ----
  976.  
  977.    muls        (multiply / 32*32->64 bits, signed /)
  978.    in:        d0, d1: integer;
  979.    call:    mathlib    muls;
  980.    out:        d1 (63..32), d0 (31..0): double longint;
  981.  
  982.  
  983.     ----
  984.     MULU
  985.     ----
  986.  
  987.    mulu        (multiply / 32*32->64 bits, unsigned /)
  988.    in:        d0, d1: integer;
  989.    call:    mathlib    mulu;
  990.    out:        d1 (63..32), d0 (31..0): double longint;
  991.  
  992.  
  993.     ----
  994.     OPEN
  995.     ----
  996.  
  997.    open        (open a file and display possible errors)
  998.    in:        a0=*name, d0=access_mode;
  999.    call:    doslib    open;
  1000.    out:        d0=file; /NULL==error/
  1001.    notes:    /access_mode =    0:  Read
  1002.                    1:  Write
  1003.                    2:  Append
  1004.                    8:  Quiet (or'ed with others)/
  1005.          /needs execlib, handler/
  1006.  
  1007.  
  1008.     -----
  1009.     ORDER
  1010.     -----
  1011.  
  1012.    order    (return higher and lower of two)
  1013.    in:        d0, d1: integer;
  1014.    call:    mathlib    order;
  1015.    out:        d0: lower, d1: higher;
  1016.  
  1017.  
  1018.     --------
  1019.     PEEKWORD
  1020.     --------
  1021.  
  1022.    peekword    (peek integer string /double longword/)
  1023.    in:        a0=*string;
  1024.    call:    strlib peekword;
  1025.    out:        d1:d0=string;
  1026.    notes:    /see getiwordu/
  1027.  
  1028.  
  1029.     -------
  1030.     PTRLIST
  1031.     -------
  1032.  
  1033.    ptrlist    (create string pointer list)
  1034.    in:        a0=*string_list; a1=*room_for_ptrlist;
  1035.            d0=max_number_of_ptrs;
  1036.    call:    strlib ptrlist;
  1037.    out:        d0=number_of_ptrs;
  1038.    notes:    /the string list in a0 should be terminated/
  1039.            /by an empty string/
  1040.            /collects the starting addresses for each/
  1041.            /string into the ptrlist./
  1042.  
  1043.  
  1044.     -----
  1045.     PUT10
  1046.     -----
  1047.  
  1048.    put10    (integer to string10 /signed/)
  1049.    in:        a0=*string; d0=integer;
  1050.    call:    numlib put10;
  1051.    out:        a0=*(NULL); d0=length;
  1052.  
  1053.  
  1054.     -----
  1055.     PUT16
  1056.     -----
  1057.  
  1058.    put16    (integer to string16 /signed/)
  1059.    in:        a0=*string; d0=integer;
  1060.    call:    numlib put16;
  1061.    out:        a0=*(NULL); d0=length;
  1062.  
  1063.  
  1064.     -------
  1065.     PUTBCPL
  1066.     -------
  1067.  
  1068.    putbcpl    (convert TO BCPL string)
  1069.    in:        a0=*string; a1=*bcpl_string;
  1070.    call:    strlib putbcpl;
  1071.    out:        -
  1072.    notes:    /the pointers are both APTRs and NOT BPTRs/
  1073.  
  1074.  
  1075.     ---------
  1076.     RANGERAND
  1077.     ---------
  1078.  
  1079.    rangerand    (generate random numbers)
  1080.    in:        d0=range;
  1081.    call:    joylib    rangerand;
  1082.    out:        d0=random_number;
  1083.    notes:    /Needs GFX/
  1084.          /'range' should be between 0 and 256/
  1085.          /'random_number' is chosen between [0..]range/
  1086.          /thus including '0' but excluding 'range'/
  1087.  
  1088.  
  1089.     --------
  1090.     READFILE
  1091.     --------
  1092.  
  1093.    readfile    (allocate a buffer and read a file into it)
  1094.    in:        a0=*name; d0=mode; /d0=0 or d0=open_quiet/
  1095.    call:    doslib    readfile;
  1096.    out:        d0=*buffer /0=error/
  1097.  
  1098.  
  1099.     --------
  1100.     REMSLASH
  1101.     --------
  1102.  
  1103.    remslash    (remove slash , if present, from end of pathname)
  1104.    in:        a0=*string;
  1105.    call:    strlib remslash;
  1106.    out:        a0=*(NULL);
  1107.  
  1108.  
  1109.     -------
  1110.     REQUEST
  1111.     -------
  1112.  
  1113.    request    (set/read requester window pointer)
  1114.    in:        d0=*window;
  1115.    call:    doslib    request;
  1116.    out:        d0=*old_window;
  1117.    notes:    /the pointers are in data register because
  1118.          there are two values with a special meaning:
  1119.          0    No default window. The requesters ap-
  1120.              pear into the WorkBench screen.
  1121.          -1    No requesters are displayed./
  1122.  
  1123.  
  1124.     -------
  1125.     REQUEST
  1126.     -------
  1127.  
  1128.    request    (display an autorequester)
  1129.    in:        a0=*window; a1=*texts; a2=*textattr (==0: deflt)
  1130.    call:    intlib    request;
  1131.    out:        d0=result; />0: true, =0: error, <0: false/
  1132.  
  1133.  
  1134.     ----
  1135.     SBLK
  1136.     ----
  1137.  
  1138.    sblk        (simple skip blanks /32, 9, 10/)
  1139.    in:        a0=*;
  1140.    call:    strlib sblk;
  1141.    out:        a0=*;
  1142.  
  1143.  
  1144.     -------
  1145.     SBORDER
  1146.     -------
  1147.  
  1148.    sborder    (draw a simple border)
  1149.    in:        d0,d1=x1,y1; d2,d3=sx,sy; a1=rport;
  1150.    call:    intlib    sborder;
  1151.  
  1152.  
  1153.     -------
  1154.     SETMASK
  1155.     -------
  1156.  
  1157.    setmask    (set a drawing mask into a rastport)
  1158.    in:        d0=mask; a1=rport;
  1159.    call:    gfxlib    setmask;
  1160.  
  1161.  
  1162.     -------
  1163.     SFORMAT
  1164.     -------
  1165.  
  1166.    sformat    (format a string)
  1167.    in:        a0=*format_string;
  1168.            a1=*output_buffer;
  1169.            d0..d7=data;
  1170.    call:    execlib sformat;
  1171.    out:        a0=a1=*output_buffer_end==*(NULL);
  1172.    notes:    /the same as "format", but the data is
  1173.            given in data registers, from d0 and higher,
  1174.            instead of a specific data stream. All the
  1175.            data must be specified as longwords, with the
  1176.            'l' specifier, since the data is entered into
  1177.            a temporary data stream allocated from stack./
  1178.  
  1179.  
  1180.     ---
  1181.     SGN
  1182.     ---
  1183.  
  1184.    sgn        (sgn(x))
  1185.    in:        d0: integer;
  1186.    call:    mathlib sgn;
  1187.    out:        d0: integer in (-1,0,1);
  1188.  
  1189.  
  1190.     -------
  1191.     SKIPBLK
  1192.     -------
  1193.  
  1194.    skipblk    (skip blanks /32, 9, 10/)
  1195.    in:        a0=*string;
  1196.    call:    numlib skipblk;
  1197.    out:        a0=*newstring; d0=num_of_skipped_chars;
  1198.  
  1199.  
  1200.     -------
  1201.     SKIPBLK
  1202.     -------
  1203.  
  1204.    skipblk    (skip blanks /32, 9, 10/)
  1205.    in:        a0=*string;
  1206.    call:    strlib skipblk;
  1207.    out:        a0=*newstring; d0=num_of_skipped_chars;
  1208.  
  1209.  
  1210.     ------
  1211.     SPUT10
  1212.     ------
  1213.  
  1214.    sput10    (short integer to string10 /signed/)
  1215.    in:        a0=*string; d0=short_integer;
  1216.    call:    numlib sput10;
  1217.    out:        a0=*(NULL);
  1218.  
  1219.  
  1220.     ---
  1221.     SQR
  1222.     ---
  1223.  
  1224.    sqr        (x²)
  1225.    in:        d0: integer;
  1226.    call:    mathlib    sqr;
  1227.    out:        d0: integer; /-1 if error/
  1228.  
  1229.  
  1230.     ----
  1231.     SQRT
  1232.     ----
  1233.  
  1234.    sqrt        (sqrt(x))
  1235.    in:        d0: integer;
  1236.    call:    mathlib    sqrt;
  1237.    out:        d0: integer; /-1 if error/
  1238.    notes:    Rounded to lower integer, if decimals in root
  1239.  
  1240.  
  1241.     ------
  1242.     STABLE
  1243.     ------
  1244.  
  1245.    stable    (seek string from table with modulo)
  1246.    in:        a0=*string, a1=*string_list, d0=*modulo;
  1247.    call:    strlib stable;
  1248.    out:        a0=*data_item /==NULL if not found/;
  1249.    notes:    /the value returned points to the data area/
  1250.            /of the string. the parameter given in d0/
  1251.            /specifies the length of the data entry./
  1252.            /this entry is overskipped between the/
  1253.            /string items. a NULL character must exist/
  1254.            /after each string./
  1255.            /condition codes are set according to the result./
  1256.  
  1257.  
  1258.     -----
  1259.     STICK
  1260.     -----
  1261.  
  1262.    stick    (read joystick direction)
  1263.    in:        d0=port_number;
  1264.    call:    joylib stick;
  1265.    out:        d0=x_direction; /left=-1,0,1=right/
  1266.          d1=y_direction; /up=-1,0,1=down/
  1267.          d2=fire_button; /0,1=pressed/
  1268.  
  1269.  
  1270.     ----
  1271.     STOP
  1272.     ----
  1273.  
  1274.    stop        (check whether SIGBREAKB_CTRL_C set)
  1275.    call:    execlib stop;
  1276.    out:        p.z=(boolean) result; /z=0: stop/
  1277.  
  1278.  
  1279.     ------
  1280.     STRCMP
  1281.     ------
  1282.  
  1283.    strcmp    (compare strings /null terminated/)
  1284.    in:        a0=*first_string; a1=*second_string;
  1285.    call:    strlib strcmp;
  1286.    out:        p.flags=result;
  1287.    notes:    /results flags as CMP first_string, second_string/
  1288.            /compares also lexicographity/
  1289.  
  1290.  
  1291.     -------
  1292.     STRCMPI
  1293.     -------
  1294.  
  1295.    strcmpi    (compare strings /case-insensitive/)
  1296.    in:        a0=*first_string; a1=*second_string;
  1297.    call:    strlib strcmpi;
  1298.    out:        p.flags=result;
  1299.    notes:    /see strcmp/
  1300.  
  1301.  
  1302.     ------
  1303.     STRCPY
  1304.     ------
  1305.  
  1306.    strcpy    (string copy /null terminated/)
  1307.    in:        a0=*source_string; a1=*target_string;
  1308.    call:    strlib strcpy;
  1309.  
  1310.  
  1311.     ------
  1312.     STREND
  1313.     ------
  1314.  
  1315.    strend    (find end of string)
  1316.    in:        a0=*string;
  1317.    call:    strlib strend;
  1318.    out:        a0=*(NULL)+1;
  1319.  
  1320.  
  1321.     ------
  1322.     STRLEN
  1323.     ------
  1324.  
  1325.    strlen    (compute string length & end address/ null terminated)
  1326.    in:        a0=*string;
  1327.    call:    strlib strlen;
  1328.    out:        d0=length; a0=(*NULL)+1;
  1329.  
  1330.  
  1331.     -------
  1332.     STRLIST
  1333.     -------
  1334.  
  1335.    strlist    (convert a ptrlist into a stringlist)
  1336.    in:        a0=*ptr_list; a1=*room_for_stringlist;
  1337.            d0=len_of_buffer;
  1338.    call:    strlib strlist;
  1339.    out:        d0=number_of_strings;
  1340.    notes:    /the check for overflow is only made/
  1341.            /between the strings, thus the value/
  1342.            /in d0 should be buffersize-<length-of/
  1343.            /longest-string>/
  1344.  
  1345.  
  1346.     ------
  1347.     STRLWR
  1348.     ------
  1349.  
  1350.    strlwr    (string to lower case /null terminated/)
  1351.    in:        a0=*string;
  1352.    call:    strlib strlwr;
  1353.  
  1354.  
  1355.     ------
  1356.     STRNTH
  1357.     ------
  1358.  
  1359.    strnth    (find nth string in list / null terminated/)
  1360.    in:        a0=*string_list; d0=(uword) count;
  1361.    call:    strlib strnth;
  1362.    out:        a0=*string; d0=(uword) $ffff;
  1363.    notes:    /high speed, 4 instructions incl. rts./
  1364.          /each string of the list is terminated/
  1365.          /with a null byte. double-null (end-of-list)/
  1366.          /will not be noticed./
  1367.  
  1368.  
  1369.     ------
  1370.     STRREV
  1371.     ------
  1372.  
  1373.    strrev    (reverse string /null-terminated/)
  1374.    in:        a0=*string;
  1375.    call:    strlib    strrev;
  1376.    notes:    /created just for fun - the 40th routine!/
  1377.  
  1378.  
  1379.     -------
  1380.     STRSCMP
  1381.     -------
  1382.  
  1383.    strscmp    (simple string compare /null terminated/)
  1384.    in:        a0=*first_string; a1=*second_string;
  1385.    call:    strlib strscmp;
  1386.    out:        p.z=(boolean) result; /eq if equals/
  1387.    notes:    /does not compare alpha order, just/
  1388.            /equality/
  1389.  
  1390.  
  1391.     --------
  1392.     STRSCMPI
  1393.     --------
  1394.  
  1395.    strscmpi    (simple string compare /case-insensitive/)
  1396.    in:        a0=*first_string; a1=*second_string;
  1397.    call:    strlib strscmpi;
  1398.    out:        p.z=(boolean) result; /eq if equals/
  1399.    notes:    /does not compare alpha order, just/
  1400.            /equality/
  1401.  
  1402.  
  1403.     ------
  1404.     STRUPR
  1405.     ------
  1406.  
  1407.    strupr    (string to upper case /null terminated/)
  1408.    in:        a0=*string;
  1409.    call:    strlib strupr;
  1410.  
  1411.  
  1412.     ----
  1413.     TEXT
  1414.     ----
  1415.  
  1416.    text        (write text into a rastport)
  1417.    in:        d0=x, d1=y; a0=*string; a1=rport;
  1418.    call:    gfxlib    text;
  1419.    notes:    /remember the baseline in Y/
  1420.  
  1421.  
  1422.     ------
  1423.     TOKCMP
  1424.     ------
  1425.  
  1426.    tokcmp    (token compare /case-insensitive/)
  1427.    in:        a0=*first_string; a1=*second_string;
  1428.    call:    strlib tokcmp;
  1429.    out:        p.z=equality; /EQ if token match/
  1430.            a0=*end_of_1st_string /if they were EQ;
  1431.            otherwise unchanged/
  1432.    notes:    /first_string may be terminated with/
  1433.            /either NULL or BLANK, the second_string/
  1434.            /must terminate with a NULL./
  1435.            /the first_string does not need to match/
  1436.            /the entire string, just the given chars/
  1437.            /from the beginning/
  1438.  
  1439.  
  1440.     -----
  1441.     TSORT
  1442.     -----
  1443.  
  1444.    tsort    (bubble-sort a ptrlist)
  1445.    in:        a0=*ptr_list;
  1446.    call:    strlib tsort;
  1447.    notes:    /a rather slow (?) way of doing this/
  1448.          /empty strings separate "units": only/
  1449.          /the units within a unit are ordered./
  1450.          /the order of units is not changed./
  1451.  
  1452.  
  1453.     ------
  1454.     TSORTI
  1455.     ------
  1456.  
  1457.    tsorti    (bubble-sort a ptrlist /case-insensitive/)
  1458.    in:        a0=*ptr_list;
  1459.    call:    strlib tsorti;
  1460.    notes:    /see tsort/
  1461.  
  1462.  
  1463.     -------
  1464.     TYPEOUT
  1465.     -------
  1466.  
  1467.    typeout    (type a text into the current default output file)
  1468.    in:        a0=*text;
  1469.    call:    doslib    typeout;
  1470.    notes:    /if the Output() returns a NULL, no text
  1471.             is output. The text is written line-by-
  1472.             line, thus permitting the user to inter-
  1473.             rupt the output by entering a character
  1474.             into the console./
  1475.  
  1476.  
  1477.     -----
  1478.     UCASE
  1479.     -----
  1480.  
  1481.    ucase    (convert character to upper case /byte/)
  1482.    in:        d0=char;
  1483.    call:    strlib ucase;
  1484.    out:        d0=newchar;
  1485.  
  1486.