CP/M/CPM_CDROM.iso/simtel/sigm/vols000/vol089/syslib1.hlp

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

Directory Manipulation Routines
Generalized Routines -- DIRF and DIRFS
Buffer Allocation Routine -- DBUFFER
Disk Parameter Information Extraction Routine -- DPARAMS
Free Space Computation Routine -- DFREE
File Size Computation Routine -- FSIZE
Directory Load Routines -- DIRLOAD and DIRSLOAD
Directory Alphabetization Routine -- DIRALPHA
Directory Entry Selection Routine -- DIRSEL
Directory Pack Routine -- DIRPACK
:Directory Manipulation Routines
     Thi≤ se⌠ oµ SYSLI┬ routine≤ concern≤ itselµ witΦ thσ loadinτ ì
oµ anΣ acces≤ oµ ß disδ director∙ fo≥ thσ genera∞ purpose≤ oµ thσ ì
user.  Included in this set of routines are the functions of:
          1.  Preallocation of buffer space for the routines
          2.  Two routines which load all undeleted directory
               entries into a buffer, constantly checking for
               memory overflow as they go
                    DIRLOAD loads the first entry for each file
                         (this is the faster of the two)
                    DIRSLOAD loads the last entry for each file
                         (this routine is required if the
                              user wishes to compute file sizes)
          3.  A routine to determine the amount of free space on
               the disk
          4.  A routine to compute the size of a file in K
          5.  A routine to sort a loaded directory by file name
               and type or by file type and name
          6.  A routine to select (by marking) a set of directory
               entries which match a given ambiguous file spec
          7.  A routine to pack the loaded directory, leaving in
               it only those entries marked by the select routine
:Generalized Routines -- DIRF and DIRFS
     Routine Name: DIRF and DIRFS
     Function║
          Thi≤ routinσ initialize≤ thσ buffe≥ area¼á load≤ ß disδ ì
directory¼á select≤á ßá se⌠á oµ file≤ froφ thσá loadeΣá director∙ ì
specifieΣá b∙á thσ user'≤ ambiguou≤ filσ namσ anΣ ßá passeΣá flaτ ì
(whicΦ indicate≤ iµ Systeφ file≤ arσ selected¼á Non-systeφá file≤ ì
arσá selected¼á al∞á use≥á area≤á arσ t∩á bσá covered¼á anΣá wha⌠ ì
particula≥á use≥ areß i≤ t∩ bσ covereΣ iµ al∞ use≥ area≤ arσá no⌠ ì
selected)¼ pack≤ thσ directory¼ anΣ alphabetize≤ thσ director∙ b∙ ì
filσ namσ anΣ filσ type.
     Iµá DIR╞ i≤ used¼á thσ processinτ proceed≤ faste≥ sincσ onl∙ ì
thσá firs⌠ entr∙ oµ eacΦ filσ i≤ loadeΣ int∩ thσá memor∙á buffer«  ì
Filσ sizinτ informatioε i≤ no⌠ includeΣ iε thi≤ load¼ however.
     Iµ DIRF╙ i≤ used¼ thσ processinτ i≤ somewha⌠ slower¼ bu⌠ thσ ì
las⌠á entr∙ fo≥ eacΦ filσ i≤ loadeΣ rathe≥ thaε thσ first«á  Filσ ì
sizinτá informatioεá i≤á containeΣá iεá thi≤á entry¼áá anΣáá thi≤ ì
informatioε caε bσ useΣ b∙ thσ FSIZ┼ routine.
     Inputs:  HL points to a dynamic buffer which extends from
               after the user's code and buffer areas to the
               end of the TPA
              DE points to the first byte of the FCB used to
               specify the ambiguous file name; only the chars
               in the FN and FT fields are significant, so this
               need not be a true FCB and may be as short as 12
               bytes
              A is the selection flag, structured as follows:
               Bit 7 - If Set, Select Non-System Files
               Bit 6 - If Set, Select System Files
               Bit 5 - If Set, Select All User Areas
               Bits 4-0 - If Bit 5 is Cleared, contains number
                    of User Area to Select
     Outputs:  HL points to the first file entry in the buffer;
                each file entry is 16 bytes long
               BC contains the number of files selected
ááááá          A contains an error flag; A=0 and Zero Flag Set
ááááá           (Z) indicates TPA overflow error during load of
ááááá           directory entries; A<>0 and NZ indicates load OK

     Registers Affected:  HL, BC, PSW
     SYSLIB Routines Called:  DBUFFER, DIRLOAD, DIRSEL, DIRPACK,
                              DIRALPHA
     Special Error Conditions:  As outline for the A register
ááááá     above.


:Buffer Allocation Routine -- DBUFFER
     Routine Name: DBUFFER
     Function:
          Thi≤á routinσ allocate≤ thσ buffe≥ spacσ necessar∙á fo≥ ì
thσá se⌠ oµ director∙ function≤ iε general«á  Iεá particular¼á i⌠ ì
allocate≤ thσ necessar∙ spacσ fo≥ thσ alphabetizatioε functioε a≤ ì
wel∞ a≤ thσ loadeΣ director∙ itself«á  Thi≤ routinσ mus⌠ bσá useΣ ì
iµá thσá DIRALPH┴á routinσá i≤á t∩ bσá late≥á useΣá t∩á sor⌠á thσ ì
directory╗á thi≤á routinσá allocate≤ al∞ thσ spacσá necessar∙á b∙ ì
DIRALPH┴ t∩ sor⌠ thσ routinσ (pointe≥ space)«  Iµ thi≤ routinσ i≤ ì
called¼ i⌠ i≤ no⌠ necessar∙ t∩ cal∞ thσ DPARAM╙ routine.
     Inputs:  HL points to the beginning address of a dynamic
ááááá          buffer area which extends to under the CCP
     Outputs:  HL points to the first byte at which the directory
ááááá           entries are to be loaded
ááááá          A=0 and Zero Flag is Set (Z) if the CCP is
ááááá           already overrun; else, A<>0 and NZ
     Registers Affected:  HL, PSW
     SYSLIB Routines Called:  DPARAMS
     Special Error Conditions:  As indicated by A reg and Z flag
:Disk Parameter Information Extraction Routine -- DPARAMS
     Routine Name:  DPARAMS
     Function:
     Thi≤á routinσá extract≤ necessar∙ informatioε froφ thσá Disδ ì
Paramete≥á Blocδ (DPB⌐ anΣ store≤ i⌠ awa∙ iε somσ globa∞á buffer≤ ì
useΣ b∙ othe≥ Disδ Director∙ Routines«  Thσ informatioε extracteΣ ì
i≤ no⌠ oµ genera∞ concerε b∙ thσ programmer«á  AL╠ TH┼ PROGRAMME╥ ì
NEED╙á T╧ KNO╫ I╙ THA╘ THI╙ ROUTIN┼ MUS╘ B┼ CALLE─ A╘ LEAS╘á ONC┼ ì
BEFOR┼ TH┼ DIRLOA─ O╥ DIRSLOA─ ROUTIN┼ I╙ CALLED«  Iµ thσ DBUFFE╥ ì
routinσá i≤á called¼á theε i⌠ i≤ no⌠ necessar∙á t∩á cal∞á DPARAM╙ ì
again.
     Fo≥ thσ informatioε oµ thσ reader¼ thσ followinτ informatioε ì
i≤ extracted:
ááááá          BLKSHF <-- Block Shift Factor (1 Byte)
ááááá          BLKMSK <-- Block Mask (1 Byte)
ááááá          EXTENT <-- Extent Mask (1 Byte)
ááááá          BLKMAX <-- Max Number of Blocks on Disk (2 Bytes)
ááááá          DIRMA╪ <-- Ma° Numbe≥ oµ Di≥ Entrie≤ (▓ Bytes)
     Thi≤á routinσ automaticall∙ adjust≤ fo≥ version≤ 1.┤ anΣ 2.▓ ì
oµ CP/═ anΣ i≤ compatablσ witΦ botΦ version≤ oµ CP/M.

     Inputs:  None
     Outputs:  None (Information Extracted into Buffers)
     Registers Affected:  None
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
:Free Space Computation Routine -- DFREE
     Routine Name: DFREE
     Function:
          Thi≤á routinσá compute≤ thσ amoun⌠ oµ freσ spacσ (iεá ╦ ì
bytes⌐ lef⌠ oε disk.
     Thσá routinσá DPARAM╙á (o≥á DBUFFER¼á sincσá i⌠á als∩á call≤ ì
DPARAMS⌐á mus⌠ bσ calleΣ beforσ thi≤ routinσ i≤ useΣ s∩ tha⌠á thσ ì
correct disk parameter information is loaded for it.
     Inputs:  None
     Outputs:  DE = Amount of Free Disk Space in K Bytes
     Registers Affected:  DE
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
:File Size Computation Routine -- FSIZE
     Routine Name: FSIZE
     Function:
          Thi≤á routinσá compute≤ thσ sizσ oµ ß filσ whosσá entr∙ ì
(whicΦá MUS╘ bσ loadeΣ b∙ DIRSLOAD⌐ i≤ pointeΣ t∩á b∙á HL«á  Thi≤ ì
routinσ wil∞ work¼ bu⌠ generall∙ returε incorrec⌠ results¼ iµ thσ ì
entr∙ pointeΣ t∩ wa≤ loadeΣ b∙ DIRLOA─ instead.
     Thσá routinσá DPARAM╙á (o≥á DBUFFER¼á sincσá i⌠á als∩á call≤ ì
DPARAMS⌐á mus⌠ bσ calleΣ beforσ thi≤ routinσ i≤ useΣ s∩ tha⌠á thσ ì
correct disk parameter information is loaded for it.
     Inputs:  HL points to first byte of file entry
     Outputs:  DE contains the file size in K Bytes
     Registers Affected:  DE
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
:Directory Load Routines -- DIRLOAD and DIRSLOAD
     Routine Name: DIRLOAD and DIRSLOAD
     Function:
          DIRLOA─á anΣá DIRSLOA─ loaΣ entrie≤ fo≥á al∞á undeleteΣ ì
file≤á oεá thσá currentl∙ loggeΣ iε disδ int∩ thσá memor∙á buffe≥ ì
pointeΣ t∩ b∙ HL«  Al∞ entrie≤ arσ 1╢ byte≤ long.
     DIRLOA─á i≤ faste≥ thaε DIRSLOAD«á  I⌠ load≤ jus⌠ thσá firs⌠ ì
entr∙ oµ eacΦ filσ oε disk«á  DIRLOAD¼á however¼á shoulΣ bσá useΣ ì
onl∙áá iµá filσá sizinτá informatioεá i≤á no⌠á requireΣá b∙áá thσ ì
application≤ program.
     DIRSLOA─á load≤á jus⌠ thσ LAS╘ entr∙ oµ eacΦ filσá oεá disk«  ì
Thi≤á entr∙ contain≤ thσ necessar∙ filσ sizinτ informatioεá whicΦ ì
ma∙ bσ useΣ b∙ FSIZ┼ t∩ computσ thσ sizσ oµ thσ loadeΣ file.
     Iµá thσá TP┴ i≤ filleΣ durinτ DIRLOA─ o≥ DIRSLOA─ anΣá therσ ì
arσ stil∞ morσ filσ entrie≤ t∩ load¼á thσ loaΣ wil∞ bσ halteΣ anΣ ì
aε erro≥ returε wil∞ bσ madσ t∩ thσ caller«á  Oε return¼á iµá A=░ ì
anΣá thσá Zer∩á Flaτá i≤ Se⌠ (Z)¼á theε ßá loaΣá erro≥á occurred╗ ì
otherwise¼ thσ loaΣ wa≤ OK.


     Inputs:  HL points to the first byte of the directory buffer
ááááá          area; this area extends from after the last buffer
ááááá          used by the applications program to the page
ááááá          before the CCP.  If alphabetization is to be done,
ááááá          the value returned in HL by DBUFFER is a correct
ááááá          input for DIRLOAD or DIRSLOAD
ááááá         A=0 and Zero Flag is Set (Z) if TPA Overflow;
ááááá          A<>0 and NZ if load OK
     Outputs:  BC is the number of files loaded into the buffer
     Registers Affected:  BC
     SYSLIB Routines Called:  None
     Special Error Conditions:  If TPA is filled and load is
ááááá     incomplete, A=0 and Zero Flag is Set (Z) as error indic
:Directory Alphabetization Routine -- DIRALPHA
     Routine Name: DIRALPHA
     Function:
          T∩ alphabetizσ thσ file≤ iε thσ director∙ pointeΣ t∩ b∙ ì
H╠á b∙ eithe≥ filσ namσ anΣ typσ (STEST.AS═ goe≤ beforσ TEST.AAA⌐ ì
o≥ b∙ filσ typσ anΣ namσ (TEST.AA┴ goe≤ beforσ STEST.ASM).
     Inputs:  HL points to first directory entry
ááááá         BC contains the number of files to sort
ááááá         ┴ i≤ thσ sor⌠ flag╗ A=░ mean≤ sor⌠ b∙ filσ namσ anΣ ì
ááááá     áááááthen file type, A<>0 means by file type and name
     Outputs:  None (directory list is sorted)
     Registers Affected:  PSW
     SYSLIB Routines Called:  PRINT
     Special Error Conditions:
ááááá     I⌠á i≤ possible¼á alth∩ highl∙ unlikel∙ froφ al∞á test≤ ì
ááááágiveεá s∩á far¼á tha⌠á DIRALPH┴ ma∙ experiencσá aεá interna∞ ì
áááááerror.  If this happens, the message:
ááááá          DIRALPHA -- Pointer Error
áááááwil∞ bσ printeΣ anΣ thσ routinσ wil∞ abor⌠ t∩ CP/M«  Iµ thi≤ ì
áááááhappens¼á pleasσá repor⌠á thi≤ probleφ anΣá bσá prepareΣá t∩ ì
áááááduplicatσ thσ exac⌠ situatioε whicΦ causeΣ thi≤ erro≥ t∩ thσ ì
áááááauthor, Richard Conn.
:Directory Entry Selection Routine -- DIRSEL
     Routine Name: DIRSEL
     Function:
          DIRSE╠á select≤á al∞á entrie≤ iε thσá director∙á buffe≥ ì
whicΦá matcΦ thσ ambiguou≤ filσ namσ specifieΣ iε thσ F╬á anΣá F╘ ì
field≤á oµá thσá FC┬ pointeΣ t∩ b∙ D┼ upoε entr∙á t∩á DIRSEL«á  ┴ ì
selectioεá flaτ i≤ als∩ passeΣ t∩ DIRSE╠ iε thσ ┴á register¼á anΣ ì
thi≤ flaτ tell≤ DIRSE╠ whethe≥ o≥ no⌠ t∩ includσ Non-Systeφ file≤ ì
anΣ Systeφ file≤ iε thσ selectioε anΣ whethe≥ t∩ selec⌠ file≤á iε ì
al∞ use≥ area≤ o≥ iε ß particula≥ use≥ area.
     DIRSE╠á identifie≤ thσ selecteΣ filσ entrie≤ b∙ settinτá thσ ì
Mos⌠á Significan⌠ Bi⌠ oµ thσ firs⌠ bytσ oµ eacΦ oµ thesσá entrie≤ ì
t∩ ▒ iµ thσ entr∙ i≤ selected«á  DIRSE╠ make≤ n∩ othe≥ change≤ t∩ ì
thσ filσ entrie≤ iε thσ director∙ buffer.

     Inputs:  HL points to the directory buffer
ááááá         D┼á point≤ t∩ thσ FC┬ containinτ thσá ambiguou≤á F╬ ì
ááááá          and FT fields; only the first 12 bytes are needed
ááááá         BC contains the number of files in the directory
ááááá         A contains a selection flag, organized as follows:
ááááá          Bit 7 - Select Non-System Files
ááááá          Bit 6 - Select System Files
ááááá          Bit 5 - Select Files in All User Areas
ááááá          Bits 4-0 - If Bit 5 is 0, indicates number of
ááááá               User Area to select files from
     Outputs:  None (MSBs of selected entries are set)
     Registers Affected:  None
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
:Directory Pack Routine -- DIRPACK and DIRNPACK
     Routine Name:  DIRPACK
     Function:
          DIRPAC╦á restructure≤ thσ director∙ buffe≥á t∩á contaiε ì
onl∙ thosσ entrie≤ markeΣ b∙ DIRSEL«á  Iε thi≤ way¼ thosσ entrie≤ ì
NO╘á markeΣá b∙ DIRSE╠ arσ discardeΣ froφ thσá buffe≥á (actually¼ ì
jus⌠á takeε ou⌠ oµ consideration¼á bu⌠ thσ content≤ oµ thσ buffe≥ ì
afte≥á thσá las⌠á selecteΣ entr∙ i≤á no⌠á guaranteeΣá t∩á contaiε ì
anythinτ significant).
     Thσá Mos⌠á Significan⌠ Bi⌠ oµ thσ firs⌠ bytσ oµ al∞á entrie≤ ì
remaininτ iε thσ director∙ buffe≥ i≤ rese⌠ t∩ ░ a≤ ß sidσá effec⌠ ì
oµ DIRPACK.
     Inputs:  HL points to the directory buffer
ááááá         BC contains the number of files in the buffer
     Outputs:  BC contains the number of files (those selected by
ááááá           DIRSEL) remaining in the directory buffer
     Registers Affected:  BC
     SYSLIB Routines Called:  None
     Special Error Conditions:  None
     Routine Name:  DIRNPACK
     Function:
          DIRNPAC╦á restructure≤ thσ director∙ buffe≥ t∩á contaiε ì
onl∙á thosσá entrie≤ NO╘ markeΣ b∙ DIRSEL«á  Iε thi≤á way¼á thosσ ì
entrie≤ markeΣ b∙ DIRSE╠ arσ discardeΣ froφ thσ buffe≥ (actually¼ ì
jus⌠ takeε ou⌠ oµ consideration¼á bu⌠ thσ content≤ oµ thσá buffe≥ ì
afte≥á thσá las⌠á selecteΣá entr∙ i≤ no⌠á guaranteeΣá t∩á contaiε ì
anythinτ significant).
     Thσá Mos⌠ Significan⌠ Bi⌠ oµ thσ firs⌠ bytσ oµá al∞á entrie≤ ì
remaininτá iε thσ director∙ buffe≥ i≤ rese⌠ t∩ ░ a≤ ß sidσ effec⌠ ì
oµ DIRNPACK.
     Thσá routinσá DIRSE╠ MUS╘ bσ calleΣ beforσ DIRNPAC╦ i≤á useΣ ì
sincσá DIRNPAC╦ use≤ aε interna∞ flaτ se⌠ b∙ DIRSE╠á (fo≥á SYSTE═ ì
and R/O information).
     Inputs:  HL points to the directory buffer
ááááá         BC contains the number of files in the buffer
     Outputs:  BC contains the number of files (those NOT selected
ááááá           by DIRSEL) remaining in the directory buffer
     Registers Affected:  BC
     SYSLIB Routines Called:  DIRPACK
     Special Error Conditions:  None