home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / JSAGE / ZSUS / PROGPACK / SCZ01BET.LBR / -CZVLB01.ZZZ / -CZVLB01.
Text File  |  1989-05-24  |  16KB  |  491 lines
  1. SmallC/Z  05/08/89
  2.  
  3. This is a list of modules and routine names in CZVLIB version 0.1. Short
  4. documentation on function and calling arguments is included.
  5.  
  6. While this may not be the most convenient possible format (as opposed to by
  7. alphabetical order or by functionality) of documentation, it was easier for
  8. me to construct and keep track of, and offers the other advantage that you
  9. can easily tell which routines are grouped in which modules. This way, you'll
  10. know, when you use a function which ones you get "free", i.e. without increase
  11. in program size.
  12.  
  13. Note that routine names that begin with "U" are in almost all cases runtime
  14. system routines, typically intended for calls from assembler.
  15.  
  16. The phrase "Intended for calls from assembler" mainly means that arguments are
  17. being passed in registers, rather than on the stack. The phrase "Intended for
  18. calls from C" means the reverse, and certainly doesn't preclude calls from
  19. assembler. There are sometimes alternate entry points into routines.
  20.  
  21. The full names are given. If you're using M80/L80 format (as opposed to SLR),
  22. bear in mind that extrnals and entries are truncated to six characters.
  23.  
  24. Last checked against SLRLIB module map: 04/30/89
  25.  
  26. copyright (c) Al Grabauskas, 1989
  27.  
  28. -------------------------------------------------------------------------------
  29.  
  30. VEDIT1
  31.     -------    VEDIT1
  32.  
  33.     Vedit1(cp,wp,len,row,col,dflt,ins,cck) 
  34.         char *cp, *wp;
  35.         int len, row, col, (*dflt)(), (*ins)(), (*cck)();
  36.  
  37.     from comments at head of source:
  38.  
  39.     Video field editor - Vedit1()
  40.     ---------------------------------------------------------------------
  41.     cp   - pointer to character buffer       (initialized  )
  42.     wp   - pointer to work buffer             (uninitialized)
  43.     len  - length of character buffer      (include null )
  44.     row  - screen row for the edit          (not checked  )
  45.     col  - screen col for the edit          (not checked  )
  46.  
  47.            any of the following can be zero if you don't want 'em
  48.  
  49.     dflt - pointer to routine for unrecognized ctl characters
  50.            (return zero to ignore, non-zero to terminate Vedit1().
  51.         this can be used to move to other fields, etc. Vedit1()
  52.         WILL NOT set the string in your buffer, leaving you your
  53.         options. the edited string will be in the work buffer
  54.         if you want it.)
  55.     ins  - pointer to insert mode fcn
  56.            (called with 0 for yes/no answer, else toggle the setting
  57.         of some flag in calling routine. insert mode is "on" by
  58.         default if you omit this by specifying 0 for it)
  59.     cck  - pointer to character check function
  60.            (called with cur char - return char to use or zero to ignore.
  61.         you can omit this if !iscntrl() is ok, and you don't want
  62.         control of chars. this is where upper case xlates would
  63.         be done or certain characters rejected.)
  64.     ---------------------------------------------------------------------
  65.     Vedit1() is an extensible field edit function designed to do all the
  66.     positional work of editing a screen input field, yet leaving enough
  67.     hooks for the caller to be able to approve/disapprove or modify
  68.     individual characters, make use of unused control characters or 
  69.     sequences, etc. it may not do everything, but it's pretty flexible
  70.     if you understand it.
  71.  
  72.     Vedit1() will copy the string at cp to the buffer at wp on entry, then
  73.     perform the screen edit getting characters from the keyboard. It will
  74.     COPY WP BACK TO CP ONLY IF THE USER EXITS WITH A CARRIAGE RETURN. This
  75.     implies two things: ^U undos go back to the value of the string at cp
  76.     on the current invocation of Vedit1(), so swapping back and forth
  77.     between fields using the (*dflt)() function "resets" the undo, because
  78.     to come back to editing the current field you must re-invoke Vedit1(),
  79.     and you must explicitly copy from wp to cp for the edit to take effect
  80.     if Vedit1() returned with any value except carriage return (i.e. the
  81.     (*dflt)() function told Vedit1() to exit on some control character).
  82.     In general, it's probably best to perform this strcpy() in the
  83.     (*dflt)() function itself, if you can set up a way for it to know
  84.     where the buffers are.
  85.  
  86.     cursor oriented operation thru Vcsrpos() and Vrcwr1() is mandatory.
  87.     it is also assumed that the field will be limited to one screen line.
  88.     these conditions are the caller's problem. a work buffer is required
  89.     so that Vedit1() doesn't have to do dynamic allocation and risk
  90.     having to make a decision about what to do if it fails.
  91.  
  92.     Vedit1() supports:
  93.         ^D        cursor right
  94.         ^F        word right
  95.         ^Q^D        right end of string
  96.         ^S or BS    cursor left
  97.         ^A        word left
  98.         ^Q^S        left end of string
  99.         ^G        delete character under cursor
  100.         DEL        delete character before cursor
  101.         ^T        delete word
  102.         ^Q^Y        delete to end of line
  103.         ^Y        delete line
  104.         ^U        undo entire edit
  105.         ^V        toggle insert mode (if (*ins)() supplied)
  106.         ^M (CR)        complete edit (update buffer)
  107.         ^[ (ESC)    cancel edit (no update to buffer)
  108.             ... and whatever else your imagination allows using
  109.             the passed functions. (*dflt)() does get called on
  110.             unused ^Q sequences.
  111.  
  112.     Vedit1() returns NULL if it was left using ESC (no change to the
  113.     buffer being edited), otherwise it returns the current character.
  114.     if a non-zero value is returned, the buffer MAY be identical to its
  115.     original contents if the user didn't type anything or just overtyped
  116.     with the original contents. normally, the value returned will be a
  117.     CR (0Dh or 13 decimal), but if Vedit1() was exited due to a non-zero
  118.     return code from (*dflt)(), it will be whatever value that was. this
  119.     allows the calling routine to distinguish a normal exit and one where
  120.     (*dflt)() has something special in mind, like jumping to another
  121.     field on the screen. note that if you want the character buffer to
  122.     contain the new string on a (*dflt)() exit, you must copy it from
  123.     the work buffer yourself.
  124.     ---------------------------------------------------------------------
  125.     functions used:
  126.         bios()
  127.         iscntrl()
  128.         ipunct()
  129.         strcpy()
  130.         strlen()
  131.         toupper()
  132.         Vcsrpos()
  133.         Vrcwr1()
  134.  
  135. VCLS                based on VLIB 1.1 Module VID1
  136.     -------    VCLS
  137.  
  138.     vcls()
  139.     clears the screen using the tcap.
  140.     intended for calls from C.
  141.     returns HL=0 if not done.
  142.  
  143. VCSRPOS
  144.     -------    VCRSPOS
  145.  
  146.     vcsrpos(row,col) int row, col;
  147.     positions the cursor at the row/column specified.
  148.     intended for calls from C.
  149.     returns HL=0 if not done.
  150.  
  151. VERAEOL                based on VLIB 1.1 Module VID2
  152.     -------    VERAEOL
  153.  
  154.     veraeol()
  155.     erases to end of line using the tcap.
  156.     intended for calls from C.
  157.     returns HL=0 if not done.
  158.  
  159. VTINIT                    based on VLIB 1.1 Module VID5
  160.     -------    VTINIT
  161.  
  162.     vtinit()
  163.     initializes the terminal using the tcap.
  164.     intended for calls from C.
  165.     returns HL=0 if not done.
  166.  
  167. VDINIT                based on VLIB 1.1 Module VID6
  168.     -------    VDINIT
  169.  
  170.     vdinit()
  171.     de-initializes the terminal using the tcap.
  172.     intended for calls from C.
  173.     returns HL=0 if not done.
  174.  
  175. VRCWRITE            new code
  176.     -------    VRCWRITE
  177.  
  178.     vrcwrite(row,col,str1,str2,...,strn)
  179.         int row, col; char str1[], str2[], ... strn[];
  180.     positions the cursor at the specified row and column,
  181.     then video writes the concatenated strings.
  182.     - the message strings can contain binary 1's ("\001") to
  183.       start standout mode and binary 2's ("\002") to end it.
  184.     - the number of strings is arbitrary and they are concatenated.
  185.     - **MUST NOT** be called from modules with NOCCARGC #defined.
  186.     intended for calls from C.
  187.     returns HL=0 if some failure occurred. 
  188.  
  189. VRCWR1
  190.     -------    VRCWR1
  191.  
  192.     vrcwr1(row,col,str) int row, col; char str[];
  193.     positions the cursor at the specified row and column,
  194.     then video writes the message pointed to. the message
  195.     - the message string can contain binary 1's ("\001") to start
  196.       standout mode and binary 2's ("\002") to end it.
  197.     - one string only.
  198.     - NOCCARGC is ok.
  199.     intended for calls from C.
  200.     returns HL=0 if not done. 
  201.  
  202. VWRITE                based on VLIB 1.1 Module VLGXYMSG
  203.     -------    VWRITE
  204.  
  205.     vwrite(str1,str2,...,strn) char str1[], str2[], ... strn[];
  206.     outputs the video string specified by the argument.
  207.     - the message strings can contain binary 1's ("\001") to
  208.       start standout mode and binary 2's ("\002") to end it.
  209.     intended for calls from C.
  210.     returns HL=0 if not some failure occurred.
  211.  
  212. VWRIT1                based on VLIB 1.1 Module VLGXYMSG
  213.     -------    VWRIT1
  214.  
  215.     vwrit1(str) char str[];
  216.     outputs the video string specified by the argument.
  217.     intended for calls from C.
  218.     returns HL=0 if not done.
  219.  
  220. VSOON                    based on VLIB 1.1 Module VID3
  221.     -------    VSOON
  222.  
  223.     vsoon()
  224.     begins standout mode using the tcap.
  225.     intended for calls from C.
  226.     returns HL=0 if not done.
  227.  
  228. VSOOFF                based on VLIB 1.1 Module VID4
  229.     -------    VSOOFF
  230.  
  231.     vsoof()
  232.     ends standout mode using the tcap.
  233.     intended for calls from C.
  234.     returns HL=0 if not done.
  235.  
  236. ZGCST                    based on Z3LIB 1.3 Module Z3MSG5
  237.     -------    ZGCST
  238.  
  239.     Zgcst()
  240.     get zcpr command status message.
  241.     intended for calls from C.
  242.     returns HL=command status message.
  243.  
  244. ZPCST                    based on above
  245.     -------    ZPCST
  246.  
  247.     Zpcst(status)
  248.     put zcpr command status message.
  249.     intended for calls from C.
  250.     returns HL=command status message.
  251.  
  252. ZAPPCL                    based on Z3LIB 1.3 Module Z3APPCL
  253.     -------    ZAPPCL
  254.  
  255.     Zappcl(str) char str[];
  256.     appends str to the tail of zcpr external command line.
  257.     intended for calls from C.
  258.     returns HL=0 if not done.
  259.  
  260. ZPCL                new code - Z3LIB routine not apropriate to C
  261.     -------    ZPCL
  262.  
  263.     Zpcl(str) char str[];
  264.     inserts str[] at front of external command line (next to excute).
  265.     intended for calls from C.
  266.     returns HL=0 if not done.
  267.  
  268. ZCLRCL                    based on Z3LIB 1.3 Module Z3CLRCL
  269.     -------    ZCLRCL
  270.  
  271.     Zclrcl()
  272.     clears zcpr external command line.
  273.     intended for calls from C.
  274.     returns HL=0 if not done.
  275.  
  276. ZGCL                    based on Z3LIB 1.3 Module Z3GCL1
  277.     -------    ZGCLSZ
  278.     -------    ZGCL
  279.  
  280.     Zgclsz()
  281.     gets size of zcpr external command line.
  282.     intended for calls from C.
  283.     returns HL=command line size.
  284.  
  285.     Zgcl()
  286.     gets pointer to external command line in HL.
  287.     intended for calls from C.
  288.     returns HL=command line pointer (and A=size in assembler)
  289.  
  290. ZGCLNXT                    based on Z3LIB 1.3 Module Z3GCL2
  291.     -------    ZGCLNXT
  292.  
  293.     Zgclnxt()
  294.     returns pointer to next command in external command line buffer.
  295.     intended for calls from C.
  296.     returns HL=0 if none.
  297.  
  298. ZSHEMPTY                based on Z3LIB 1.3 Module Z3SHEMPTY
  299.     -------    ZSHEMPTY
  300.  
  301.     Zshempty()
  302.     tests the shell stack to see if it is empty.
  303.     intended for calls from C.
  304.     returns HL=non-zero if empty,
  305.         HL=0 otherwise.
  306.  
  307. ZSHFULL                    based on Z3LIB 1.3 Module Z3SHFULL
  308.     -------    ZSHFULL
  309.  
  310.     Zshfull()
  311.     tests to see if the Shell Stack is full.
  312.     intended for calls from C.
  313.     returns HL=non-zero if full or no stack,
  314.         HL=0 otherwise.
  315.  
  316. ZSHPOP                    based on Z3LIB 1.3 Module Z3SHPOP
  317.     -------    ZSHPOP
  318.  
  319.     Zshpop()
  320.     pops the top element off of the Shell Stack if possible.
  321.     intended for calls from C.
  322.     returns HL=0 if successful,
  323.         HL=1 if no shell stack,
  324.         HL=2 if shell stack already empty.
  325.  
  326. ZSHPUSH                based on Z3LIB 1.3 Module Z3SHPUSH
  327.     -------    ZSHPUSH
  328.  
  329.     Zshpush(str) char str[];
  330.     pushes string, including terminating 0, onto shell stack if possible.
  331.         - this actually copies as many bytes as will fit into a shell entry - 
  332.           even those following the terminating null, as long as a null occurs
  333.           withing the shell entry. this accomodates putting extra stuff on the
  334.           shell stack if the program so desires.
  335.     intended for calls from C.
  336.     returns HL=0 if successful, 
  337.         HL=1 if no shell stack available
  338.         HL=2 if shell stack is full
  339.         HL=3 if string is too long for shell stack entry
  340.  
  341. USYSINIT
  342.     -------    USYSINIT
  343.  
  344.     Usysinit
  345.     initializes the zcpr environment in a SmallC/Z program.
  346.     initialization includes aiming global pointer Uvidptr at the zcpr
  347.     tcap in memory, and overriding the default cpm argv[0] by copying the
  348.     name the program was invoked by from the efcb to the global CSYSLIB
  349.     module string Uarg1[]. zcpr functions bypassed if zenvck() fails.
  350.     called by Uentry as it walks the initilization vector.
  351.  
  352. UERRSMSG
  353.     -------    UERRSMSG
  354.  
  355.     Uerrsmsg
  356.     system level routine to write the null terminated message
  357.     following the assembler call to the console. 
  358.     intended for calls from assembler.
  359.     usage:    
  360.         call    Uerrsmsg
  361.         db    'Message text...',0
  362.     affects AF, SP and HL registers.
  363.  
  364. UEXCD
  365.     -------    UEXCD
  366.  
  367.     Uexcd
  368.     zcpr exit code interpreter. calls standard runtime exit code
  369.     message function sysexcod(), then if zenvck() returns affirmative,
  370.     sets the zcpr program error flag to value of code passed to exit().
  371.     Called by exit() as it walks the exit vector through Usetecd pointer.
  372.  
  373. UGOTOXY                based on VLIB 1.1 Module VID7
  374.     -------    UGOTOXY
  375.  
  376.     Ugotoxy
  377.     positions the cursor at the row/column specified.
  378.     intended for calls from assembler. usage:    
  379.         ld    h,row
  380.         ld    l,column
  381.         call    Ugotoxy
  382.     returns with A=0 and Z set if not done.
  383.  
  384. UGSH                based on Z3LIB 1.3 Module Z3GSH
  385.     -------    UGSH1
  386.     -------    UGSH2
  387.     -------    ZGETSH
  388.  
  389.     Ugsh1
  390.     returns Hl=address of the shell stack in HL,
  391.            B=size of each shell stack entry,
  392.            A=number of entries possible in the shell stack.
  393.         A=0 and Zero Flag Set (Z) if there is no shell stack.
  394.  
  395.     Ugsh2
  396.     intended for calls from assembler.
  397.     returns HL=address of the shell stack in HL,
  398.            DE=size of each shell stack entry,
  399.            A=B=number of entries possible in the shell stack
  400.         A=0 and Zero Flag Set (Z) if there is no shell stack.
  401.  
  402.     Zgetsh()
  403.     intended for calls from C.
  404.     returns HL=0 if no shell stack,
  405.         HL=shell stack pointer if there is.
  406.  
  407.  
  408. UVIDSKP                based on VLIB 1.1 Module VIDA
  409.     -------    UVIDSKP
  410.  
  411.     Uvidskp
  412.     skips over video string pointed to by HL and points to the byte
  413.     following it.
  414.     intended for calls from assembler.
  415.     returns HL=0 if not done.
  416.     affects AF and HL registers.
  417.  
  418. UVIDOUT                based on VLIB 1.1 Module VID8
  419.     -------    UVIDOUT
  420.  
  421.     Uvidout
  422.     outputs the video string pointed to by HL and the delay contained
  423.     in register DE.
  424.     intended for calls from assembler. usage:    
  425.         ld    DE,delay
  426.         ld    HL,string
  427.         call    Uvidout
  428.     returns same as Uvidelay.
  429.  
  430. UVIDELAY                based on VLIB 1.1 Module VID9
  431.     -------    UVIDELAY
  432.  
  433.     Uvidelay
  434.     pauses for the number of milliseconds indicated by the A register.
  435.     assumes a ZCPR environment and uses it to determine processor speed.
  436.     intended for calls from assembler.
  437.     affects no registers.
  438.  
  439. UCOUT                based on disassembly of SYSLIB 3.6 Module COUT
  440.     -------    UCOUT
  441.  
  442.     Ucout
  443.     outputs the character in register A to the console.
  444.     intended for calls from assembler.
  445.     affects no registers.
  446.  
  447. ZENVCK                new code
  448.     -------    ZENVCK
  449.     Zenvck()
  450.     checks if zcpr environment. (fails if program not installed).
  451.     intended for calls from C.
  452.     returns HL=pointer to env descriptor and NZ flag if Z environment
  453.         HL=0 and Z flag if not
  454.  
  455.     * also contains CZVLIB version number
  456.     * db 'SCZCZV0.1',0
  457.  
  458. ZGEFCB                    based on Z3LIB 1.3 Module Z3GEFCB
  459.     -------    ZGEFCB
  460.  
  461.     Zgefcb()
  462.     returns a pointer to external fcb. used to get name of program.
  463.     intended for calls from C.
  464.     returns HL=efcb ptr.
  465.  
  466. ZGPGMERR                based on Z3LIB 1.3 Module Z3MSG3
  467.     -------    ZGPGMERR
  468.  
  469.     Zgpgmerr()
  470.     returns value of program error flag.
  471.     intended for calls from C.
  472.     returns HL<and>A<both>=pgm error flag value.
  473.  
  474. ZPPGMERR            based on Z3LIB 1.3 Module Z3MSG4
  475.     -------    ZERROR
  476.     -------    ZPPGMERR
  477.  
  478.     Zerror(val) char val; <or> Zppgmerr(val) char val;
  479.     sets zcpr program error flag to val.
  480.     intended for calls from C.
  481.     returns HL=0 if not done.
  482.  
  483. ZGMSG                    based on Z3LIB 1.3 Module Z3GMSG
  484.     -------    ZGMSG
  485.  
  486.     Zgmsg()
  487.     returns pointer to zcpr message bytes.
  488.     intended for calls from C.
  489.     returns HL=msg ptr.
  490.  
  491.