CP/M/CPM_CDROM.iso/simtel/sigm/vols000/vol098/syslib.hlp

Text File | 1985-02-09 | 14KB | 357 lines

Directory Manipulation Routines
Numeric String Evaluation Routines
Byte-Oriented File Input/Output Routines
CP/M File Input/Output Routines
User/Disk Manipulation Routines
File Name String Parser (FNAME) and FCB Init (INITFCB)
ZCPR2-Specific File Name String Parser (ZFNAME) and Support
ZCPR2 Feature-Specific Routines
Input Line Editors
String Output Routines
NumeriπáOutpu⌠ Routine≤
String and Value Comparison Routines
Character-Oriented Input/Output Routines
Math Routines
CRC Routines
Random Number Generator Routines
Sort Routines
Misπellaneous Routines
::SYSLIB1.HLP
::SYSLIB2.HLP
::SYSLIB3.HLP
::SYSLIB4.HLP
:User/Disk Manipulation Routines

     Thi≤á i≤á ßá se⌠ oµ fou≥ routine≤ whicΦ allo≈á thσá use≥á t∩ ì
readil∙ movσ arounΣ betweeε disk≤ anΣ use≥ areas«  Thesσ routine≤ ì
are:
          PUTUD -- to save away the current disk/user
          GETUD -- to restore the disk/user saved by PUTUD
          RETUD -- to return the current disk/user
          LOGUD -- to log the user into a specified disk/user

     PUTU─á anΣ GETU─ arσ designeΣ t∩ bσ useΣ a≤ ßá placσá marke≥ ì
anΣá returεá combination«á  The∙ arσ intendeΣ t∩ bσ useΣ iεá codσ ì
sequences like the following:

          CALL PUTUD     ; Mark current location
          < move around on disks/users >
          CALL GETUD     ; Return to marked location

     RETU─ anΣ LOGU─ arσ t∩ bσ useΣ t∩ finΣ ou⌠ wherσ thσ prograφ ì
is (RETUD) and to enter a specific disk/user area (LOGUD).

     Routine Name:  PUTUD
     Function║
          PUTU─á save≤ thσ curren⌠ use≥ anΣ disδ number≤ awa∙ fo≥ ì
late≥á retrieva∞ b∙ GETUD«á  PUTU─ anΣ GETU─ arσ intendeΣá t∩á bσ ì
useΣá t∩á savσ anΣ restorσ thσ curren⌠ disδ anΣ use≥ arounΣá somσ ì
set of operations in another user/disk area.
     Inputs:  None
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  RETUD
     Specia∞á Erro≥ Conditions║  None


     Routine Name:  GETUD
     Function║
          GETU─á restore≤á thσ curren⌠ use≥ anΣá disδá whicΦá wa≤ ì
saved by PUTUD.
     Inputs:  None
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  BDOS
     Specia∞á Erro≥ Conditions║  None


     Routine Name:  LOGUD
     Function║
          LOGU─ log≤ iε thσ disδ specifieΣ b∙ thσ ┬ registe≥ (B=░ ì
fo≥ Disδ A) and the user specified by the C register.
     Inputs:  B=Disk (B=0 for Disk A), C=User
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  BDOS
     Specia∞á Erro≥ Conditions║  None


     Routine Name:  RETUD
     Function║
          RETU─á return≤ thσ number≤ oµ thσ curren⌠ use≥ iε ├ anΣ ì
current disk in B (B=0 for disk A).
     Inputs:  None
     Outputs:  B=Disk (B=0 for disk A), C=User
     Registers Affected:  BC
     SYSLIB Routines Called:  BDOS
     Specia∞á Erro≥ Conditions║  None


:File Name String Parser (FNAME) and FCB Init (INITFCB)
     Routine Name: FNAME
     Function:
          FNAM┼á i≤ ß filσ namσ scanner«á  Pointinτ t∩ thσá firs⌠ ì
characte≥ oµ ß filσ namσ specificatioε oµ thσ form:

ááááá          du:filename.typ

wherσá an∙á par⌠ oµ thσ specificatioε i≤ optional¼á thi≤á routinσ ì
fill≤ iε aε FC┬ witΦ zeroe≤ (3╢ bytes)¼á properl∙ initialize≤ thσ ì
F╬ (Filσ Name⌐ fielΣ iµ 'filenameº i≤ presen⌠ anΣ F╘ (Filσá Type⌐ ì
fielΣ iµ 'typº i≤ present¼ anΣ return≤ thσ numbe≥ oµ thσ selecteΣ ì
disδá (iεá thσ rangσ froφ ▒ fo≥ ┴ t∩ 1╢ fo≥ P⌐ iµ 'dº i≤á presen⌠ ì
anΣá thσ numbe≥ oµ thσ selecteΣ use≥ (iε thσ rangσ froφ ░á t∩á 3▒ ì
anΣá thσ questioε marδ '?º character⌐ iµ 'uº i≤ present«á  Iµ 'dº ì
i≤ no⌠ present¼ 0FF╚ i≤ returneΣ fo≥ i⌠ t∩ indicatσ curren⌠ disk¼ ì
anΣá iµ 'uº i≤ no⌠ present¼á 0FF╚ i≤ returneΣ fo≥ i⌠ t∩á indicatσ ì
curren⌠ user.


     Thσ strinτ pointeΣ t∩ b∙ H╠ i≤ no⌠ ß conventiona∞ strinτá iε ì
thσá sensσá oµ thσ res⌠ oµ thσ SYSLI┬ routines«á  Thi≤ strinτá i≤ ì
terminateΣ b∙ an∙ oµ thσ followinτ delims¼á a≤ opposeΣ b∙á simpl∙ ì
alway≤ beinτ terminateΣ b∙ ß binar∙ zero«  Thσ delimite≥ lis⌠ is:

ááááá          <NULL or Binary 0>       <SP or Space>
ááááá          =    _    ;    ,    <    >

     Thσ followinτ arσ valiΣ examples:
ááááá          test.txt   <-- FN=TEXT  FT=TXT, B reg = 0FFH,
ááááá                         C reg = 0FFH
ááááá          a:t        <-- FN=T  FT=<SP>, B reg = 1,
ááááá                         C reg = 0FFH
ááááá          5:t        <-- FN=T  FT=<SP>, B reg = 0FFH,
ááááá                         C reg = 5
ááááá          c10:x.y    <-- FN=X  FT=Y, B reg = 3,
ááááá                         C reg = 10


     Inputs:  HL points to the first byte of the target string
ááááá               (which ends in a delimiter)
ááááá         DE pts to the first byte of a 36-byte long FCB
     Outputs:  B=Disk Number (1 for A to 16 for P, or 0FFH if
ááááá               no disk specified)
ááááá          C=User Number (0 to 31 or '?' for all users, or
ááááá               0FFH if no user specified)
ááááá          HL points to the character which ended the scan
ááááá          A = 0 and Zero Flag Set (Z) if invalid Disk or User
ááááá               Specified; A = 0FFH and NZ if no error
     Registers Affected: PSW, BC, HL
     SYSLIB Routines Called:  CAPS
     Special Error Conditions:  None


     Routine Name:  INITFCB
     Function║
ááááá     INITFC┬á simpl∙á clear≤ al∞ oµ thσ field≤ oµ ßá 36-bytσ ì
áááááFC┬á t∩á zer∩ excep⌠ fo≥ thσ F╬ anΣ F╘ (Filσ Namσá anΣá Filσ ì
áááááType⌐ fields¼ whicΦ i⌠ leave≤ untouched.

     Inputs:  DE = pointer to FCB buffer
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  FILLB
     Special Error Conditions:  None
::SYSLIB8.HLP
::SYSLIB9.HLP
::SYSLIBA.HLP
:String Output Routines -- PRINT, LPRINT, PSTR, LPSTR
     Routine Names:  PRINT, LPRINT
     Function║
          Prin⌠á strinτ pointeΣ t∩ b∙ thσ returε addres≤ oεá CON║ ì
(PRINT⌐á o≥ LST║á (LPRINT)«á  Strinτ i≤ terminateΣ b∙ ß binar∙ 0«  ì
Contro∞ i≤ returneΣ t∩ bytσ followinτ string.
     Inputs:  Return Address = pointer to string to be printed
     Outputs:  HL points to byte after string
               (string is printed on CON: or LST:)
     Registers Affected:  HL
     SYSLIB Routines Called:  PSTR (for PRINT); LSTR (for LPRINT)
     Specia∞ Erro≥ Conditions:
          Thσ strinτ MUS╘ bσ terminateΣ b∙ ß binar∙ 0!!!

     Routine Names:  PSTR, LPSTR
     Function║
          Prin⌠á strinτ pointeΣ t∩ b∙ H╠ oε CON║á (PSTR⌐ o≥á LST║ ì
(LPSTR)«  Strinτ i≤ terminateΣ b∙ ß binar∙ 0.
     Inputs:  HL = pointer to string to be printed
     Outputs:  HL pts to the byte following the terminating 0
                (string is printed on CON: or LST:)
     Registers Affected:  HL
     SYSLI┬á Routine≤ Called║  CCOUT¼á COU╘ (fo≥ PSTR)╗
                               LCOUT¼ LOU╘ (fo≥ LPSTR)
     Specia∞ Erro≥ Conditions:
          Thσ strinτ MUS╘ bσ terminateΣ b∙ ß binar∙ 0!!!
::SYSLIB5.HLP
:String and Value Comparision Routines
     Routine Name:  COMPHD
     Function║
          Comparσ H╠ t∩ DE«á  Oε return¼á Zer∩ Flaτ Se⌠ =╛ HL=DE¼ ì
Carr∙ Flaτ Se⌠ =╛ HL<DE.
     Inputs:  HL, DE -- Values to compare
     Outputs:  Zero and Carry Flags
     Registers Affected:  PSW
     SYSLIB Routines Called:  -None-
     Special Error Conditions:  -None-

     Routine Names:  COMPB, COMPBC
     Function║
          Vecto≥ Comparσ Routines«  Comparσ thσ vecto≥ pointeΣ t∩ ì
b∙á H╠ witΦ tha⌠ pointeΣ t∩ b∙ D┼ (Vector≤ arσ oµ equa∞á length)«  ì
Vector≤á arσ ┬ byte≤ lonτ fo≥ COMP┬ anΣ B├ byte≤ lonτ fo≥ COMPBC«  ì
Oεá exit¼á Zer∩á Flaτ Se⌠ indicate≤ tha⌠ vector≤á arσá identical╗ ì
Carr∙ Flaτ Se⌠ indicate≤ tha⌠ thσ vecto≥ pointeΣ t∩ b∙ H╠ i≤ les≤ ì
thaε thσ vecto≥ pointeΣ t∩ b∙ DE.
     Inputs:  HL, DE -- Pointers to vectors to compare
              B (for COMPB), BC (for COMPBC) -- number of bytes in vectors
     Outputs:  Zero and Carry Flags
     Registers Affected:  PSW
     SYSLIB Routines Called:  -None-
     Special Error Conditions:  -None-

     Routine Name:  SCANNER
     Function║
          SCANNE╥ scan≤ thσ vecto≥ oµ byte≤ pointeΣ t∩ b∙ H╠á fo≥ ì
thσá vecto≥ oµ byte≤ pointeΣ t∩ b∙ DE«á  Thσ HL-bytσ vecto≥ i≤á ┬ ì
byte≤ lonτ anΣ thσ DE-bytσ vecto≥ i≤ ├ byte≤ long«  Oε return¼ iµ ì
found¼ H╠ point≤ t∩ thσ beginninτ locatioε withiε thσ origina∞ H╠ ì
vecto≥á oµá thσ locateΣ vecto≥ anΣ thσ Zer∩ Flaτ i≤ Set╗á iµá no⌠ ì
found¼ Zer∩ Flaτ i≤ no⌠ se⌠ anΣ H╠ i≤ no⌠ affecteΣ (point≤ t∩ thσ ì
beginninτ oµ thσ origina∞ HL-bytσ vector).
     Inputs:  HL = Pointer to vector to be scanned
              DE = Pointer to vector to scan for
              B = Number of bytes in HL-vector
              C = Number of bytes in DE-vector
     Outputs:  If found, Zero Set and HL pts to located vector
               If not found, Zero Reset and HL unaffected
     Registers Affected:  PSW, HL
     SYSLIB Routines Called:  -None-
     Specia∞á Erro≥á Conditions║á  Automatiπá succes≤á iµá vecto≥ ì
searcheΣ fo≥ i≤ null.

     Routine Name:  INSTR
     Function║
          INSTRIN╟á Function«á  Scaε thσ strinτ pointeΣ t∩ b∙á H╠ ì
fo≥ thσ strinτ pointeΣ t∩ b∙ DE«á  ┴ strinτ i≤ ß vecto≥ oµá byte≤ ì
terminateΣ b∙ ß binar∙ 0.
          Oε return¼á iµ found¼ Zer∩ Flaτ i≤ Se⌠ anΣ H╠ point≤ t∩ ì
1s⌠ bytσ oµ substrinτ withiε scanneΣ string╗á iµ no⌠ found¼á Zer∩ ì
Flaτ i≤ no⌠ se⌠ anΣ H╠ i≤ no⌠ affected.
     Inputs:  HL = Pointer to string to be scanned
              DE = Pointer to string to scan for
     Outputs:  If found, Zero Set and HL pts to located substring
               If not found, Zero Reset and HL unaffected
     Registers Affected:  PSW, HL
     SYSLIB Routines Called:  -None-
     Specia∞ Erro≥ Conditions:
          Automatiπ succes≤ iµ strinτ searcheΣ fo≥ i≤ null.
::SYSLIB6.HLP
::SYSLIB7.HLP
:CRC Routines -- CRCCLR, CRCUPD, CRCDONE, CRC1's, CRC2's
     Thσá CR├á Routine≤ ma∙ bσ useΣ t∩ checδ thσ validit∙á oµá aε ì
incominτ seria∞ bytσ streaφ oµ arbitrar∙ length«á  Thesσ routine≤ ì
computσ anΣ checδ ß truσ 16-bi⌠ Cycliπ Redundanc∙ Codσ (CRC).
     The use of these routines will guarantee detection of:
          1) all single- and double-bit errors
          2) all errors with an odd number of error bits
          3) all burst errors of length 16 or less
     Additionally, the following statistics:
          1) 99.9969% of all 17-bit error bursts
          2) 99.9984% of all possible longer error bursts

     Thσá followinτá screeε displa∙ illustrate≤ ß typica∞ wa∙á t∩ ì
usσ thesσ routines:

     CRC$MAKE:                ; ROUTINE TO ESTABLISH OUTGOING CRC VALUE
          CALL CRCCLR    ; CLEAR CRC
          <loop CALLing CRCUPD>    ; ACQUIRE VALUES
          CALL CRCDONE   ; GET VALUE
          SHLD CRCVAL    ; SAVE VALUE
     CRC$CHECK:          ; ROUTINE TO CHECK INCOMING CRC VALUE
          CALL CRCCLR    ; CLEAR CRC
          <loop CALLing CRCUPD>    ; ACQUIRE VALUES
          CALL CRCDONE   ; GET VALUE
          XCHG           ; VALUE IN DE
          LHLD CRCVAL    ; GET FIRST VALUE IN HL
          CALL COMPHD    ; COMPARE HL TO DE
          JNZ  ERROR     ; CRC'S DON'T MATCH IF NOT EQUAL

     Thσá followinτá screeε display≤ describσ thσá CR├á routines«  ì
Thσá CRC- routine≤ usσ thσ X^16+X^12+X^5+▒ polynomial¼á thσ CRC1- ì
routine≤á usσá thσá X^16+X^15+X^2+▒á polynomial¼á anΣá thσá CRC2-ì
routines use the X^16+X^15+X^13+X^7+X^4+X^2+X+1 polynomial.
     Routine Name:  CRCCLR, CRC1CLR, CRC2CLR
     Function║
          Clea≥á thσá interna∞ CR├ Accumulato≥ iε preparatioεá t∩ ì
CR├ computation.
     Inputs:  None
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  None
     Special Error Conditions:  None

     Routine Name:  CRCUPD, CRC1UPD, CRC2UPD
     Function:
          Updatσ thσ CR├ Accumulato≥ valuσ witΦ thσ nex⌠ byte.
     Input:  A=byte to be included in CRC
     Outputs:  None
     Registers Affected:  None
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
     Routine Name:  CRCDONE, CRC1DONE, CRC2DONE
     Function║
          Terminatσáá CR├á valuσá accumulatioεá anΣá returεáá thσ ì
calculateΣ 16-bi⌠ CR├ value.
     Inputs:  None
     Output:  HL = calculated CRC value
     Registers Affected:  HL
     SYSLIB Routines Called:  None
     Special Error Conditions:  None

:Random Number Generator Routines

     The Random Number Generator Routines are:

          RNDINIT - Initializes the Generator Seed on user
                         keypress
          RNDSEED - Allows user to provide a seed
          RND - Returns a Pseudo-Random Number


     Routine Name:  RNDINIT
     Function║
          RNDINI╘ enter≤ ß countinτ loop¼ waitinτ fo≥ thσ use≥ t∩ ì
strikσ ß ke∙ a⌠ hi≤ console«  I⌠ theε set≤ thσ seeΣ valuσ fo≥ thσ ì
randoφ numbe≥ generato≥ baseΣ upoε it≤ coun⌠ valuσ a⌠ thσ instan⌠ ì
of keypress.  The seed value is an 8-bit quantity.
     Inputs:  None (User Keypress)
     Outputs:  None  (Seed is set)
     Registers Affected:  None
     SYSLIB Routines Called:  CONDIN, RND
     Specia∞á Erro≥ Conditions║  None

     Routine Name:  RNDSEED
     Function║
          Thi≤á routinσá allow≤ thσ use≥ t∩ providσ ß seeΣá valuσ ì
fo≥á thσ randoφ numbe≥ generator«á  Thσ seeΣ i≤ passeΣ iεá thσá ┴ ì
register.
     Inputs:  A = Seed
     Outputs:  None  (Seed is set)
     Registers Affected:  None
     SYSLIB Routines Called:  RND
     Specia∞á Erro≥ Conditions║  None


     Routine Name:  RND
     Function║
          Thi≤ i≤ thσ user-callablσ randoφ numbe≥ generator«á  I⌠ ì
return≤á ßá pseudo-randoφ numbe≥ (8-bit⌐ iε thσ ┴á registe≥á wheε ì
called.
     Inputs:  None
     Outputs:  A = Random Number
     Registers Affected:  PSW
     SYSLIB Routines Called:  None
     Specia∞á Erro≥ Conditions║  None

::SYSLIBB.HLP
::SYSLIBC.HLP