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 / BEEHIVE / ZSUS / Z3HELP-6.LBR / ZA.LBR / Z3LIB5.HZP / Z3LIB5.HLP
Text File  |  2000-06-30  |  19KB  |  531 lines
  1. Introduction   ZCPR3 Utilities
  2.  Named Dir/DU Conversion  - DIRTDU, DUTDIR
  3.  Resolve Dir References   - DNSCAN et al
  4.  Parse Command Line       - PARSER
  5.  Path Search for File     - PFIND
  6.  Program Loader (Chain)   - PRGLOAD
  7.  Console Output (Quiet)   - Qxxx
  8.  Locate ROOT Directory    - ROOT
  9.  Shell Stack Routines     - SHxxx
  10.  Delay Routines           - WAITs
  11.  Log into ZCPR3 FCB DU    - Z3LOG
  12.  Return Z3LIB Version #   - Z3LVER
  13.  Parse Token              - ZPRSFN, ZFNAME
  14.  ZCPR 3.3 Parsers         - PARSE2, Z33FNAME, REPARSE, SCAN
  15.  Check Z33 Parse Results  - FCB1CHK, FCB2CHK, FCBCHK
  16.  Print Load Module Data   - PRTTYPE
  17.  Z33 Internal Prog Name   - GETNAME, PRTNAME
  18.  Highest Useable Memory   - GZMTOP
  19. :            Introduction to ZCPR3 Utilities 
  20.  
  21. These utilities provide a number of convenient functions for
  22. ZCPR3 Programmers.  Access to directories, conversion from text
  23. string names to directory reference values, command and command
  24. line parsing, quiet output routines, shell stack manipulation,
  25. delay routines, and other ZCPR3-specific functions are provided.
  26.  
  27. :                   DIRTDU/DUTDIR 
  28.  
  29. DIRTDU - Convert specified DIR name to DU equivalent
  30.  
  31.   ENTER: HL = Address of first character of DIR Name
  32.   EXIT : HL = Points to delimiter at end of Name
  33.          BC = DU, B=Disk (A=0,..P=15), C =User (0..31)
  34.           A <> 0, Zero Flag Clear (NZ) if Found
  35.               A = 0, Zero Flag Set (Z) if NOT Found
  36.   USES : AF,BC,HL
  37.  
  38.  Usage:  This routine converts a DIR name consisting of
  39.   a string of up to eight characters terminated by any
  40.   character other than a digit or letter to its DU:
  41.   equivalent found in the Named Directory Buffer.
  42.  
  43. DUTDIR - Convert specified DU to DIR equivalent
  44.  
  45.   ENTER: BC = DU, B=Disk (A=0,..P=15), C=User (0..31)
  46.   EXIT : HL = Pointer to 8-char Name String
  47.           A <> 0, Zero Flag Clear (NZ) if Found
  48.               A = 0, Zero Flag Set (Z) if NOT Found
  49.   USES : AF,HL
  50.  
  51.  Usage:  This routine searches the Named Directory for the
  52.   specified DU.  If an entry exists for the corresponding DU, a
  53.   pointer is returned to the 8-character name (followed by an
  54.   8-character password).
  55.  
  56. :                DNSCAN - DUSCAN - DIRSCAN 
  57.  
  58. DNSCAN - Resolve Directory Name using both DU and DIR
  59.  
  60.   ENTER: HL = Address of the first char of Directory Name
  61.           A = 0  - Scan DU before DIR,
  62.           A <> 0 - Scan DIR before DU
  63.   EXIT : BC = DU, B=Disk (A=0,..P=15), C=User (0..31)
  64.           A <> 0, Zero Flag Clear (NZ) if Found
  65.               A = 0, Zero Flag Set (Z) if NOT Found
  66.   USES : AF,BC
  67.  
  68.  Usage:  This routine attempts to resolve a candidate Directory
  69.   name by checking both DIR and DU formats in specified order.
  70.   The candidate name may be up to eight characters terminated
  71.   by a delimiter such as a space, comma, period, dash, a char
  72.   less than space, etc.  If found, the DU is returned in BC.
  73.  
  74. DUSCAN - Resolve addressed string in DU form
  75.  
  76.   ENTER: HL = Address of string (up to 8 chars)
  77.   EXIT : BC = DU.  B=Disk (A=0,..P=15), C=User (0..31)
  78.           A <> 0, Zero Flag Clear (NZ) if Valid DU form
  79.               A = 0, Zero Flag Set (Z) if NOT Valid
  80.   USES : AF,BC
  81.  
  82.  Usage:  This routine resolves the DU form of a string
  83.   addressed by HL.  The DU string  is stored in a buffer up to
  84.   eight chars long, and is terminated by a delimiter, which may
  85.   be a char less than a space, equal sign (=), underscore (_),
  86.   period (.), comma (,), Less than (<) or greater than (>).
  87.  
  88. DIRSCAN - Resolve addressed in DIR form
  89.  
  90.   ENTER: HL = Address of string (up to 8 chars)
  91.   EXIT : BC = DU.  B=Disk (A=0,..P=15), C=User (0..31)
  92.           A <> 0, Zero Flag Clear (NZ) if Valid DU form
  93.               A = 0, Zero Flag Set (Z) if NOT Valid
  94.   USES : AF,BC
  95.  
  96.  Usage:  This routine resolves the DIR form of a string
  97.   addressed by HL.  The DU string is stored in a buffer up to
  98.   eight chars long, and is terminated by a delimiter, which may
  99.   be a char less than a space, equal sign (=), underscore (_),
  100.   period (.), comma (,), Less than (<) or greater than (>).
  101.  
  102. :PARSER - Parse Complete Command Line
  103.  
  104.   ENTER: HL = Address of Command line
  105.           A = 0, Scan DIR before DU, <> 0=Scan DU before DIR
  106.   EXIT : HL = address of next command (0 or leading ;)
  107.          DE = address of FCB with command name  (verb. COM)
  108.           A = 0, Zero Flag Set (Z) if Ok
  109.               A = Number of question marks, Zero Clear (NZ)
  110.                    if verb contains one or more "?" chars
  111.   USES : AF,DE,HL
  112.  
  113.  Usage:  This routine parses a complete command up to an ending
  114.   Null or MCL delimiter (usually a semicolon).  It parses and
  115.   initializes all elements per the ZCPR3 Command conventions to
  116.   include FCB1 at 005CH, FCB2 at 006CH and the default Buffer
  117.   (TBUFF) at 0080H.  The command name is returned in an FCB
  118.   addressed by DE.
  119.  
  120. :PFIND - Search for specified file along Search Path
  121.  
  122.   ENTER: DE = Address of an FCB
  123.           A <> 0 to search current Dir, 0 if No Current search
  124.   EXIT : BC = DU.  B=Disk (A=0,..P=15), C=User (0..31)
  125.           A <> 0, Zero Flag Clear (NZ) if Found
  126.               A = 0, Zero Flag Set (Z) if NOT Found
  127.   USES : AF,BC
  128.  
  129.  Usage:  Used to locate a file along the ZCPR3 Search Path.
  130.   When located, the Disk and User where the file was found are
  131.   returned.
  132.  
  133. :PRGLOAD - Load and Execute specified program (Chain)
  134.  
  135.   ENTER: DE = Addresses the first 12 bytes of an FCB
  136.   EXIT : None
  137.   USES : All regs.  If routine returns, Load was a failure
  138.  
  139.  Usage:  This routine is a "Chain" function which loads the
  140.   program indicated by the first 12 bytes addressed by DE into
  141.   memory at 100H and transfers control to it.  The loader and
  142.   FCB used forthe load are relocated to just under the Command
  143.   Processor after PRGLOAD begins execution, so the TPA is free
  144.   for the load.  Care should be taken to ensure that the system
  145.   stack (located out of the TPA in a safe area) is used instead
  146.   of a stack in the TPA which may be overwritten during load.
  147.  
  148.   If PRGLOAD returns to the calling program, an error in
  149.   loading occurred.  If all goes well, the loaded program
  150.   executes successfully.
  151.  
  152. :                      Qxxxx 
  153.  
  154. These routines output their values only if the Quiet Flag is
  155. clear (0).  If the Quiet Flag is TRUE (not 0), then no values
  156. are output.
  157.  
  158. This class of routines includes the following:
  159.  
  160.     QCOUT     Console Character Output with Control
  161.     QCRLF     New Line
  162.     QOUT     Console Character Output
  163.     QPRINT     String Output (Return Address)
  164.     QPSTR     String Output (HL)
  165.  
  166. QCOUT - Print character on Console if Not Quiet
  167.  
  168.   ENTER: A = Character to print
  169.   EXIT : None
  170.   USES : None
  171.  
  172.  Usage:  This routine is comparible to the SYSLIB routine COUT
  173.   except that it only prints if the Quiet Flag is OFF.  Control
  174.   characters are printed as a karet (^) followed by the char
  175.   offset by 40H (1 outputs as ^A).
  176.  
  177. QCRLF - Print a New Line (CR LF pair) if Not Quiet
  178.  
  179.   ENTER: None
  180.   EXIT : None
  181.   USES : None
  182.  
  183.  Usage:  This routine corresponds to the SYSLIB routine CRLF
  184.   except that in is only sent to the Console if the Quiet Flag
  185.   is OFF (0).
  186.  
  187. QOUT - Print w/o Control Char Processing if Not Quiet
  188.  
  189.   ENTER: A = Character to Output
  190.   EXIT : None
  191.   USES : None
  192.  
  193.  Usage:  QOUT outputs the character in A without control
  194.   character processing (1 outputs as binary 1) if the Quiet
  195.   Flag is OFF (0).
  196.  
  197. QPRINT - Inline print of string if Not Quiet
  198.  
  199.   ENTER: None.  String at Return Address
  200.   EXIT : None
  201.   USES : None
  202.  
  203.  Usage:  This routine prints a Null-terminated string whose
  204.   address is contained on the Stack Top if the Quiet Flag is
  205.   OFF (0).  Execution resumes at the byte following the Null
  206.   after the string is printed.
  207.  
  208. QPSTR - Print Null-terminated string if Not Quiet
  209.  
  210.   ENTER: HL = Address of first character of the string
  211.   EXIT : None
  212.   USES : None
  213.  
  214.  Usage:  QPSTR is the same as QPRINT, except that printing is
  215.   from a register as opposed the inline address from the Stack.
  216.  
  217. :ROOT - Return DU for the last Directory in Search Path
  218.  
  219.   ENTER: None
  220.   EXIT : BC = DU.  B=Disk (A=0,..P=15), C=User (0..31)
  221.   USES : BC
  222.  
  223.  Usage:  This routine provides a convenient way to find the
  224.   last directory in a Path expression (ROOT Directory).  No
  225.   path optimization is performed.
  226.  
  227.   Note:  This routine is sometimes not consistent with the
  228.   ZCPR3 Command Processor if the MINPATH (Minimize Path Expres-
  229.   sion) option is selected.  ROOT advances to the last
  230.   referenced directory in the path without minimization, which
  231.   ZCPR3 minimizes the search and may resolve a path to end
  232.   (with duplication) at a directory other than the physically
  233.   last directory in the path.
  234.  
  235. :                         SHxxx 
  236.  
  237. This set of routines supports Shell Stack manipulation.  The
  238. following routines are provided:
  239.  
  240.     SHEMPTY - test to see if Shell Stack is empty
  241.     SHFULL  - test to see if Shell Stack is full
  242.     SHPOP   - pop top string off of Shell Stack
  243.     SHPUSH  - push string onto Shell Stack
  244.  
  245. A Shell Stack is implemented as a series of strings (recom-
  246. mended size is 32 bytes/string, and the stack should contain
  247. at least four of these strings).  The top element of a Shell
  248. Stack specifies the command line to be executed as a Shell
  249. by the ZCPR3 CP.  This command line is copied into the
  250. Multiple Command Line Buffer for execution.
  251.  
  252. SHEMPTY - Return status of Shell Stack
  253.  
  254.   ENTER: None
  255.   EXIT : A <> 0, Zero Flag Clear (NZ) if Not Empty
  256.              A = 0, Zero Flag Set (Z) if Empty or None
  257.   USES : AF
  258.  
  259.  Usage:  This routine simply provides the current state of the
  260.   Shell Stack.  The Zero Flag indicates whether or not Shell
  261.   Stack space is available.
  262.  
  263. SHFULL - Determine if the Shell Stack is Full
  264.  
  265.   ENTER: None
  266.   EXIT : A <> 0, Zero Flag Clear (NZ) if Stack NOT Full
  267.              A = 0, Zero Set (Z) if Stack FULL or None
  268.   USES : AF
  269.  
  270.  Usage:  This routine simply returns a flag indicating if the
  271.   Shell Stack is full or non-existant.
  272.  
  273. SHPOP - Pop Top Element from Shell Stack and discard
  274.  
  275.   ENTER: None
  276.   EXIT : A = 0, Zero Flag Set (Z) if Ok
  277.              A = Error Code, Zero Clear (NZ) as:
  278.           1 - NO Shell Stack, Zero Clear
  279.           2 - Shell Stack empty, Zero Clear
  280.   USES : AF
  281.  
  282.  Usage:  This routine removes the top element from the Shell
  283.   Stack, if possible, and discards it.  Error codes report if
  284.   the operation was successful, or the reason for the error.
  285.  
  286. SHPUSH - Push Null-terminated string onto Shell Stack
  287.  
  288.   ENTER: HL = Addresses Null-term string to push on Stack
  289.   EXIT :  A = 0, Zero Flag Set (Z) if Successful
  290.              A = Return code as --
  291.           1 - No Shell Stack available, Zero Clear
  292.           2 - Shell Stack is full, Zero Clear
  293.           3 - String too long for entry, Zero Clear
  294.   USES : AF
  295.  
  296.  Usage:  This routine performs needed functions to push Null-
  297.   terminated strings onto the Shell Stack.  Returned status
  298.   shows the results of the action.
  299.  
  300. :                         WAITs 
  301.  
  302. The following routines provide a software delay based upon the
  303. processor speed value in the ZCPR3 Environment Descriptor.
  304. These routines simply delay for the indicated period of time
  305. (approximately) and then return.  No registers are affected.
  306.  
  307. The routines are:
  308.  
  309.     WAIT1S    - delay for 1 second
  310.     WAIT1MS   - delay for 0.001 second
  311.     WAITP1S   - delay for 0.1 second
  312.  
  313. WAIT1S - Wait for approximately One second
  314.  
  315.   ENTER: None
  316.   EXIT : None
  317.   USES : None
  318.  
  319.  Usage:  This routine is used to pause for approximately one
  320.   second based on the Processor Speed in the ENV and CPU type.
  321.  
  322. WAIT1MS - Wait for approximately One Millisecond
  323.  
  324.   ENTER: None
  325.   EXIT : None
  326.   USES : None
  327.  
  328.  Usage:  This routine is used to pause for approximately one
  329.   millisecond (.001 sec) based on the Processor Speed in the
  330.   ENV and CPU type.
  331.  
  332. WAITP1S - Wait for approximately One-Tenth Second
  333.  
  334.   ENTER: None
  335.   EXIT : None
  336.   USES : None
  337.  
  338.  Usage:  This routine is used to pause for approximately one
  339.   tenth of a second based on the Processor Speed and CPU type.
  340.  
  341. :Z3LOG - Log into DU contained in a specified ZCPR3 FCB
  342.  
  343.   ENTER: DE = Addresses first byte of ZCPR3 FCB
  344.   EXIT : None
  345.   USES : None
  346.  
  347.  Usage:  This routine logs into the Drive and User contained in
  348.   a specified ZCPR3 FCB.  The drive is in Byte 0 of the FCB
  349.   (A=1,..P=16), and the User (0..31) is in Byte 13.  This is
  350.   the standard format used by ZCPR3 to store a complete DU
  351.   reference in an FCB.
  352.  
  353. :Z3LVER - Return Version Number of Z3LIB.REL
  354.  
  355.   ENTER: None
  356.   EXIT : HL = Version Number (H=Major, L=Minor) in binary
  357.   USES : HL
  358.  
  359.  Usage:  This routine is used to highlight the Z3LIB Version in
  360.   linked programs, or in debugging with different versions.
  361.  
  362. :ZPRSFN / ZFNAME - Parse FCB Token
  363.  
  364.   ENTER: HL = Address of first char of token
  365.          DE = Address of 36-byte FCB
  366.           A = Flag: 0 - scan for DIR form before DU
  367.                     1 - scan for DU form before DIR
  368.   EXIT : HL = Address of char after token
  369.           A = Number of question marks in Filename.Typ,
  370.                 Zero Flag set accordingly
  371.   USES : AF,HL
  372.  
  373.  Usage:  These two routines perform the identical function of
  374.   parsing a complete FCB token in the ZCPR3 Command Processor
  375.   sense.  Tokens may take the form of "Dir:Filename.Typ",
  376.   "DU:Filename.Typ", "Filename.Typ", etc.  The resulting FCB
  377.   contains the filename and type and a proper DU reference.
  378.   (see PARSER, which is related).
  379.  
  380.   ZFNAME is a literal interpretation of the code within the
  381.   ZCPR3 Command Processor, while ZPRSFN is a more efficient
  382.   body of code but uses more buffer space.
  383.  
  384. :Z33FNAME - Parse single token from Ext Command Buff           (*)
  385.  
  386.   ENTER: DE - points to user-defined FCB to receive token
  387.   EXIT : HL - points to delimiter in Command Buffer
  388.   USES : HL
  389.   REQUIREMENTS: ZCPR 3.3 or later Command Processor
  390.  
  391.  Usage:  This routine parses a single token from the External
  392.   Command Buffer to a specified FCB.  It uses the SCAN entry
  393.   in ZCPR 3.3 or later.
  394.  NOTE: You must insure that the Command Processor has not
  395.          been overwritten to use this function.
  396.  
  397. PARSE2 - Parse Command Line using ZCPR 3.3 REPARSE entry      (*)
  398.  
  399.   ENTER: HL = address of the Command line to re-parse
  400.   EXIT : None.  Line is reparsed and FCBs filled
  401.   USES : None
  402.   REQUIREMENTS: ZCPR 3.3 or later Command Processor
  403.  
  404.  Usage:  This routine parses a specified command line to the
  405.   default FCBs at 5CH and 6CH.
  406.  NOTE: You must insure that the ZCPR 3.3 or later Command
  407.          Proc. has not been overwritten to use this routine.
  408.  
  409. REPARSE - Reparse Default Command Line one token later        (*)
  410.  
  411.   ENTER: None
  412.   EXIT : None.  The Command Line is reparsed
  413.   USES : None
  414.   REQUIREMENTS: ZCPR 3.3 or later Command Processor
  415.  
  416.  Usage:  This routine reparses the current Command Line
  417.   starting one token after current setting and sets the
  418.   default FCBs.
  419.  NOTE: You must insure that the Command Processor has
  420.          not been overwritten.
  421.  
  422. SCAN - Scan Single Token from Specified Command Line          (*)
  423.  
  424.   ENTER: HL = Points to Command Line to scan
  425.      DE = Points to FCB to receive parsed token
  426.   EXIT : None.  Token is parsed
  427.   USES : None
  428.   REQUIREMENTS: ZCPR 3.3 or later Command Processor
  429.  
  430.  Usage:  This routine parses a single token from a User-
  431.   specified Command Line into a specified FCB using the
  432.   SCAN entry in ZCPR 3.3 or later.
  433.  NOTE: You must insure that the Command Processor has not
  434.          been overwritten.
  435.  
  436. :FCB1CHK - Examine first default FCB for validity.             (*)
  437.  FCB2CHK - Examine second default FCB for validity.            (*)
  438.  
  439.   ENTER: None
  440.   EXIT :  A = 0, Zero Set (Z) if FCB has valid name
  441.           A <> 0, Zero Clear (NZ) if Error or no name
  442.   USES : AF
  443.   REQUIREMENTS: FCB parsed by ZCPR 3.3 or later
  444.  
  445.  Usage:  Examine the default FCBs at locations 5CH (FCB1CHK)
  446.   and 6CH (FCB2CHK) for validly parsed filenames from ZCPR 3.3
  447.   or later parsers.  Errors are due to DU: out of range,
  448.   illegal Named Directory, or illegal password.
  449.  
  450. FCBCHK - Examine specified FCB for validity.                  (*)
  451.  
  452.   ENTER: DE = address of an FCB to check
  453.   EXIT :  A = 0, Zero Set (Z) if FCB has valid name
  454.           A <> 0, Zero Clear (NZ) if Error or No Name
  455.   USES : AF
  456.   REQUIREMENTS: FCB parsed by ZCPR 3.3 or later
  457.  
  458.  Usage:  Examine the FCB at a specified address for validly
  459.   parsed filename by ZCPR 3.3 or later type parse sequence.
  460.   Errors are due to DU: out of range, illegal Named Direc-
  461.   tory, or illegal password.  
  462.  
  463. :PRTTYPE - Print Load Module Type and Address                  (*)
  464.  
  465.   ENTER:  A = Program type (1..4)
  466.      HL = Program Load address
  467.   EXIT : None.  The Type and address are printed on CON:
  468.   USES : None
  469.  
  470.  Usage:  This routine is most often used in Extended
  471.   Processors and utilities to display load information.
  472.   It prints a message to the CON: device containing Load
  473.   Module Type (3 or 4) and the Load address in Hex.
  474.  
  475. Example:
  476.     EXT    PRTTYPE        ; Declare the routine
  477.     ...
  478.     JP    BEGIN        ; ZCPR 3 Header structure
  479.     DEFB    'Z3ENV'        ; .ID String
  480. TYPE:    DEFB    3        ; ..Module Load Type
  481. Z3EADR:    DEFW    $-$        ; ...Candidate ENV Address
  482. START:    DEFW    9800H        ; Type 3 Starting Addr = 9800H
  483.  
  484. BEGIN:    ...            ; Initial setup, set stack, etc
  485.     LD    A,(TYPE)    ; Get the load module type
  486.     LD    HL,START    ; ..and load starting address
  487.     CALL    PRTTYPE        ; Print them to the Console
  488.     ...            ; ..continue on
  489.  
  490. :GETNAME - Return pointer to Current Program Name              (*)
  491.  
  492.   ENTER: None
  493.   EXIT :  A <> 0, Zero Clear (NZ) if External FCB exists
  494.               A = 0, Zero Set (Z) if NO External FCB
  495.      HL = Address of Internal Name buffer
  496.                         (valid only if ext FCB exists)
  497.   USES : AF,DE,HL
  498.   REQUIREMENTS: External FCB must be defined to function
  499.  
  500.  Usage: This routine returns a pointer to the currently
  501.   executing program by accessing the External FCB defined
  502.   in the Z3 Environment Descriptor.  It is useful for
  503.   identifying the Real program name when re-executed with
  504.   a "GO" command or equivalent facility.
  505.  
  506. PRTNAME - Print Program Name from Internal Buffer             (*)
  507.  
  508.   ENTER: None
  509.   EXIT : None.  The name is printed to CON:
  510.   USES : None
  511.  
  512.  Usage:  This routine simply prints the current program
  513.   name from an internally-held buffer to the Console.
  514.  
  515. :GZMTOP - Return Last Usable TPA Memory Address                (*)
  516.  
  517.   ENTER: None
  518.   EXIT : HL = Last usable memory address in TPA
  519.   USES : HL
  520.  
  521.  Usage:  This routine may be used to determine the top of
  522.   the available TPA.  It uses the Extended Environment, if
  523.   available, otherwise it calculates the CCP base from BIOS
  524.   Warm Boot addr.  It also accomodates sensing for resident
  525.   RSXes.  The address returned is the last byte below a
  526.   Page boundary (L=0FFH) for an added safety margin.
  527.      For Example, if the CCP begins at 0C000H and no RSXes
  528.   are present, this routine would return 0BFFFH.  On the
  529.   other hand, if an RSX exists with a protect address of
  530.   0BC6CH, GXMTOP will return 0BBFFH.
  531.