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 / CPM / LANGUAGS / FORTRAN / CPMLIB.ARK / CPMLIB.DOC < prev    next >
Text File  |  1982-01-12  |  17KB  |  533 lines
  1.             CPMLIB.DOC
  2.  
  3.     Version 1.0            January 12, 1982
  4.  
  5. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
  6.  
  7. CPMLIB is a library of routines which can be called from
  8. Microsoft FORTRAN-80 programs to interface with selected
  9. CP/M CCP and BDOS functions.
  10. By means of this library, the following CP/M
  11. functions may be added to any FORTRAN program:
  12.  
  13.     Input a character from the console without a
  14.     terminating carriage return.
  15.     (Two forms of this function are supported.)
  16.  
  17.     Test for the presence of a file.
  18.  
  19.     Erase a file or group of files.
  20.  
  21.     Rename a file.
  22.  
  23.     Get the command line "tail" as program input.
  24.  
  25. The library is made up of three levels of subroutines.
  26.  
  27. The highest level are those routines normally called from
  28. within a user program.  These are described first.
  29. The "high-level" routines are:
  30.     EXIST .... Test for presence of a file.
  31.     ERASE .... Erase a file.
  32.     GETCMD ... Get the command line "tail".
  33.     INCHR .... Input character from console (with echo).
  34.     INKEY .... Input character from console (without echo).
  35.     RENAME ... Rename a file.
  36.  
  37. Second is a group of routines which provide support to the
  38. high-level routines.  These may also be called from a user
  39. program if required.  They are described at the end of this
  40. document.
  41. The "low-level" routines are:
  42.     FCB$ ..... Build a CP/M File Control Block.
  43.     FNAME$ ... Extract a CP/M File Name from a string.
  44.     MAP$ ..... Map character to upper case.
  45.     ERROR$ ... Print error messages from the library.
  46.  
  47. Finally, there are the machine-level calls to BDOS. Normally
  48. a user program will not call these routines directly.
  49.  
  50. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
  51.  
  52. To use the library, you just need to CALL the appropriate
  53. routines from your program.   Compile as you normally would.
  54. Then, in the LINK-80  step, request a search of CPMLIB prior
  55. to the normal search of FORLIB.  For example:
  56.  
  57.     L80 prog,CPMLIB/S,FORLIB/S,prog/N/E
  58.  
  59. The search of CPMLIB should come before the search of FORLIB.
  60.  
  61. The routines available in the CPMLIB are:
  62.  
  63.     CALL EXIST  ( NDRIVE, STRING, NBYTES, IOK )
  64.     CALL ERASE  ( NDRIVE, STRING, NBYTES )
  65.     CALL GETCMD ( STRING )
  66.     CALL INCHR  ( NOPT, CHAR )
  67.     CALL INKEY  ( NOPT, CHAR )
  68.     CALL RENAME ( NDRIVE, FNOLD, FNNEW, NBOLD, NBNEW )
  69.  
  70.     CALL FCB$   ( STRING, LSTRNG, FCB )
  71.     CALL FNAME$ ( STRING, LSTRNG, NDRIVE, FILNAM )
  72.     CALL MAP$   ( AIN, AOUT )
  73.     CALL ERROR$ ( NERROR, ANAME, ARRAY )
  74.  
  75.  
  76. A detailed description of each routine follows:
  77.  
  78.  
  79.  
  80.  
  81.  
  82. + + + + + + + + + + + + HIGH LEVEL ROUTINES + + + + + + + + + +
  83.  
  84.                         Primary Entry Points
  85.                         into the Library
  86.  
  87.  
  88.                         * * * * * * * * * *
  89.                         *                 *
  90.                         *    E R A S E    *
  91.                         *                 *
  92.                         * * * * * * * * * *
  93.  
  94.  
  95.       Usage: CALL ERASE ( NDRIVE, STRING, NBYTES )
  96.  
  97.         NDRIVE = < integer >
  98.         STRING = < byte array >
  99.         NBYTES = < integer >
  100.  
  101. Erase a CP/M file.
  102.  
  103. The file being erased should be closed before this routine
  104. is called.  Otherwise, duplicate FCB's will exist for the
  105. file and unpredictable results may occur.
  106.  
  107. Input Arguments:
  108. NDRIVE ... Drive number (1=A:, 2=B:, etc.)
  109.            If entered as zero, then the currently-logged
  110.            drive is used unless the STRING array contains
  111.            a drive specification in the file name.
  112. STRING ... A byte array containing a valid CP/M file name.
  113.            The name may contain a drive specification if
  114.            desired.
  115. NBYTES ... The number of bytes in the STRING array.
  116.            If entered as zero, the STRING will be assumed
  117.            to be 11 bytes long, with the file name blank
  118.            filled (in the same format as for a Microsoft
  119.            OPEN call).  In this mode, the drive cannot be
  120.            passed in the file name.
  121.  
  122. Note: The drive may be specified in several ways. If more
  123.       than one specification is used, they must all agree
  124.       or a DRIVE CONFLICT error will be generated.
  125.       If the file to be erased cannot be found,
  126.       a NO FILE error will be generated.
  127.  
  128. Output Arguments:
  129.     (none)
  130.  
  131.  
  132. Examples of valid calls:
  133.  
  134.     CALL ERASE ( 0, 'b:ab.x', 6 )
  135.     CALL ERASE ( 2, 'AB.X', 4 )
  136.     CALL ERASE ( 2, 'AB      X  ', 11 )
  137.     CALL ERASE ( NDR, FILNAM, NLONG )
  138.  
  139. Assuming that, in the last example, NDR = 2, FILNAM is a byte
  140. array containing "ab.x", and NLONG = 4, then all of the
  141. examples will erase the file AB.X on drive B:.
  142.  
  143.  
  144.  
  145.                         * * * * * * * * * *
  146.                         *                 *
  147.                         *    E X I S T    *
  148.                         *                 *
  149.                         * * * * * * * * * *
  150.  
  151.  
  152.       Usage: CALL EXIST ( NDRIVE, STRING, NBYTES, IOK )
  153.  
  154.         NDRIVE = < integer >
  155.         STRING = < byte array >
  156.         NBYTES = < integer >
  157.         IOK    = < integer >
  158.  
  159. Test to see if a file exists.
  160.  
  161.  
  162. Input Arguments:
  163. NDRIVE ... Drive number (1=A:, 2=B:, etc.)
  164.            If entered as zero, then the currently-logged
  165.            drive is used unless the STRING array contains
  166.            a drive specification in the file name.
  167. STRING ... A byte array containing a valid CP/M file name.
  168.            The name may contain a drive specification if
  169.            desired.
  170. NBYTES ... The number of bytes in the STRING array.
  171.            If entered as zero, the STRING will be assumed
  172.            to be 11 bytes long, with the file name blank
  173.            filled (in the same format as for a Microsoft
  174.            OPEN call).  In this mode, the drive cannot be
  175.            passed in the file name.
  176.  
  177. Note: The drive may be specified in several ways. If more
  178.       than one specification is used, they must all agree
  179.       or a DRIVE CONFLICT error will be generated.
  180.       If the file to be erased cannot be found,
  181.       a NO FILE error will be generated.
  182.  
  183. Output Arguments:
  184. IOK ...... Returned value:
  185.            0 = file doesn't exist
  186.            1 = file exists
  187.  
  188.  
  189.  
  190.                         * * * * * * * * * *
  191.                         *                 *
  192.                         *   G E T C M D   *
  193.                         *                 *
  194.                         * * * * * * * * * *
  195.  
  196.  
  197.       Usage: CALL GETCMD ( ARRAY )
  198.  
  199.         ARRAY  = < byte array >
  200.  
  201. This routine will get the "command line tail" and pass it
  202. into the calling program.
  203. Leading blanks are stripped off.
  204.  
  205. The "tail" is that part of the command line that follows
  206. the program name.  For example, if the following line
  207. were typed at the console following a CP/M prompt:
  208.  
  209.        b:foo options:a,c,d,f,l
  210.  
  211. the system would load program FOO.COM from drive B: and the
  212. "tail" would be the character string OPTIONS:A,C,D,F,L.
  213.  
  214. CP/M will always map the command line to upper case.
  215.  
  216. The user's program must interpret the "tail". All this
  217. routine does is pass it to the FORTRAN program, after 
  218. leading blanks are stripped off.
  219.  
  220. Some other considerations:
  221.  
  222.     You MUST get the "tail" before any disk operations
  223.     are performed in the program.  Otherwise, CP/M may
  224.     overwrite the command line buffer during a disk
  225.     operation.  Thus, you should call this routine as
  226.     one of the first activities in your program.
  227.  
  228.     You should scan the "tail" carefully, watching out
  229.     for trailing and imbedded blanks.  The line
  230.     will be passed exactly as typed except for mapping
  231.     to upper case.
  232.  
  233. Input arguments:
  234.     (none)
  235.  
  236. Output arguments:
  237. ARRAY .... This is a byte array, which must be dimensioned
  238.            in the calling program to a length sufficient to
  239.            hold the entire "tail".  Otherwise, important
  240.            data or program instructions may be overwritten
  241.            by the command line information.  Dimensioning
  242.            the variable to 80 bytes is usually sufficient.
  243.            The FIRST BYTE of the returned array will contain
  244.            the number of characters to follow.  Only these
  245.            characters are valid.  The remainder of the array
  246.            will be unchanged from its original contents, or
  247.            will contain "garbage".
  248.  
  249.  
  250.  
  251.                         * * * * * * * * * *
  252.                         *                 *
  253.                         *    I N C H R    *
  254.                         *                 *
  255.                         * * * * * * * * * *
  256.  
  257.  
  258.       Usage: CALL INCHR ( NOPT, CHAR )
  259.  
  260.         NOPT   = < integer >
  261.         CHAR   = < byte >
  262.  
  263. This subroutine reads a character from the console.
  264. The character is immediately echoed to the console.
  265. It is also returned as the value of the argument CHAR.
  266.  
  267. If no character is pending at the console, execution
  268. halts until a character is typed.
  269.  
  270. The character is transmitted as soon as it is typed.
  271. The RETURN or ENTER key is not required to complete the 
  272. entry.
  273.  
  274. Input Arguments:
  275. NOPT ..... Option for interpretation of input character.
  276.            (Add the following values together to determine
  277.             the value to use.)
  278.            0 = (no option)
  279.            1 = (no option)
  280.            2 = map lower case alphabet to upper case
  281.            4 = stop execution if ctrl-C
  282.  
  283. Output Arguments:
  284. CHAR ..... The resulting character.
  285.  
  286.  
  287.  
  288.                         * * * * * * * * * *
  289.                         *                 *
  290.                         *    I N K E Y    *
  291.                         *                 *
  292.                         * * * * * * * * * *
  293.  
  294.  
  295.       Usage: CALL INKEY ( NOPT, CHAR )
  296.  
  297.         NOPT   = < integer >
  298.         CHAR   = < byte >
  299.  
  300. This function reads a character from the console.
  301. The character is not echoed to the console.
  302. It is returned as the value of the argument CHAR.
  303.  
  304. If no character is pending at the console, the
  305. NUL character (ASCII 0) is returned and execution
  306. of the program continues.
  307.  
  308. The character is transmitted as soon as it is typed.
  309. The RETURN or ENTER key is not required to complete the 
  310. entry.
  311.  
  312. Input Arguments:
  313. NOPT ..... Option for interpretation of input character.
  314.            (Add the following values together to determine
  315.             the value to use.)
  316.            0 = (no option)
  317.            1 = wait for a character to be typed
  318.            2 = map lower case alphabet to upper case
  319.            4 = stop execution if ctrl-C
  320.  
  321. Output Arguments:
  322. CHAR ..... The resulting character.
  323.  
  324.  
  325.  
  326.                         * * * * * * * * * *
  327.                         *                 *
  328.                         *   R E N A M E   *
  329.                         *                 *
  330.                         * * * * * * * * * *
  331.  
  332.  
  333.       Usage: CALL RENAME ( NDRIVE, FNOLD, FNNEW, NBOLD, NBNEW )
  334.  
  335.         NDRIVE = < integer >
  336.         FNOLD  = < byte array >
  337.         FNNEW  = < byte array >
  338.         NBOLD  = < integer >
  339.         NBNEW  = < integer >
  340.  
  341. Rename a CP/M file.
  342.  
  343. The file being renamed should be closed before this routine
  344. is called.  Otherwise, duplicate FCB's will exist for the
  345. file and unpredictable results may occur.
  346.  
  347. Input Arguments:
  348. NDRIVE ... Drive number (1=A:, 2=B:, etc.)
  349.            If entered as zero, then the currently-logged
  350.            drive is used unless the FNOLD or FNNEW array
  351.            contains a drive specification in the file name.
  352. FNOLD .... A byte array containing a valid CP/M file name.
  353. FNNEW .... A byte array containing a valid CP/M file name.
  354.            The name may contain a drive specification if
  355.            desired.
  356.            FNOLD is the old name; FNNEW is the new name.
  357. NBOLD ... The number of bytes in the FNOLD array.
  358. NBNEW ... The number of bytes in the FNNEW array.
  359.            If entered as zero, the array will be assumed
  360.            to be 11 bytes long, with the file name blank
  361.            filled (in the same format as for a Microsoft
  362.            OPEN call).  In this mode, the drive cannot be
  363.            passed in the file name.
  364.  
  365. Note: The drive may be specified in several ways. If more
  366.       than one specification is used, they must all agree
  367.       or a DRIVE CONFLICT error will be generated.
  368.       If the new file name already exists, a FILE ALREADY
  369.       EXISTS error will be generated.  If the old file 
  370.       cannot be found, a NO FILE error will be generated.
  371.  
  372. Output Arguments:
  373.     (none)
  374.  
  375.  
  376. Examples of valid calls:
  377.  
  378.     CALL RENAME ( 0, 'b:ab.x', 'cd.y', 6, 4 )
  379.     CALL RENAME ( 0, 'ab.x', 'b:cd.y', 4, 6 )
  380.     CALL RENAME ( 2, 'ab.x', 'cd.y', 4, 4 )
  381.     CALL RENAME ( 2, 'AB      X  ', 'CD      Y  ', 0, 0 )
  382.     CALL RENAME ( NDR, FIL1, FIL2, NB1, NB2 )
  383.  
  384. Assuming that, in the last example, NDR = 2, FIL1 is a byte
  385. array containing "ab.x", FIL2 is a byte array containing
  386. "cd.y", NB1 = 4, and NB2 = 4,  then all of the
  387. examples will rename the file AB.X to CD.Y on drive B:.
  388.  
  389.  
  390.  
  391. + + + + + + + + + + + + LOW  LEVEL ROUTINES + + + + + + + + + +
  392.  
  393.                         Service Routines for
  394.                         High-Level Routines
  395.  
  396.  
  397.  
  398.                         * * * * * * * * * *
  399.                         *                 *
  400.                         *     F C B $     *
  401.                         *                 *
  402.                         * * * * * * * * * *
  403.  
  404.  
  405.       Usage: CALL FCB$ ( STRING, LSTRNG, FCB )
  406.  
  407.         STRING = < byte array >
  408.         LSTRNG = < integer >
  409.         FCB    = < byte array >
  410.  
  411. Subroutine to build a valid File Control Block (FCB)
  412.  
  413. Input arguments:
  414. STRING ... Input string ( a byte array ) of length LSTRNG
  415. LSTRNG ... Integer value is length of STRING array in bytes.
  416.  
  417. Output arguments:
  418. FCB ...... The completed FCB ( a byte array ) which must
  419.            be 36 bytes long.  The first 12 bytes will be
  420.            initialized to the drive and file specified
  421.            in STRING. The remainder will be zeroed.
  422.  
  423.  
  424.  
  425.                         * * * * * * * * * *
  426.                         *                 *
  427.                         *   F N A M E $   *
  428.                         *                 *
  429.                         * * * * * * * * * *
  430.  
  431.  
  432.       Usage: CALL FNAME$ ( STRING, LSTRNG, NDRIVE, FILNAM )
  433.  
  434.         STRING = < byte array >
  435.         LSTRNG = < integer >
  436.         NDRIVE = < integer >
  437.         FILNAM = < byte array >
  438.  
  439. Subroutine to extract a CP/M file name from an input
  440. character string.
  441. Complete error trapping is NOT included in this routine.
  442. Thus, the programmer should excercize some caution in
  443. the use of this routine.
  444. Asterisks (*) are expanded into questions for the file
  445. name and file type, and drive information is extracted
  446. if it is included in the string as the first character
  447. followed by a colon (:).
  448. Thus, all valid CP/M file descriptions will be handled
  449. properly.
  450.  
  451. Input Arguments:
  452. STRING ... Input string ( a byte array ) of length LSTRNG
  453. LSTRNG ... Integer value is length of STRING array in bytes.
  454.  
  455. Output Arguments:
  456. NDRIVE ... Integer value of drive number:
  457.            0 = logged in drive
  458.            1 = drive A:
  459.            2 = drive B:
  460.            etc.
  461. FILNAM ... Output string ( a byte array ) of length 12.
  462.            The first byte duplicates the drive value in
  463.            NDRIVE.  The remaining bytes are the name and
  464.            extension, blank-filled to exactly 11 characters.
  465.  
  466. The format of the output arguments is such that they serve
  467. two purposes:
  468.  
  469. 1) To construct a Microsoft FORTRAN call to the OPEN subroutine,
  470.    use the form:
  471.        CALL OPEN ( lun, FILNAM(2), NDRIVE )
  472.    where 'lun' is the unit number.  Specifying FILNAM(2) in
  473.    the argument list passes the address of the second element
  474.    which is the first character of the 11-byte file name.
  475.  
  476. 2) To construct a CP/M file control block (FCB), use the
  477.    FILNAM array as the first 12 bytes of the FCB, and the
  478.    drive specification will be placed in the first byte as
  479.    required.
  480.  
  481.  
  482.  
  483.                         * * * * * * * * * *
  484.                         *                 *
  485.                         *     M A P $     *
  486.                         *                 *
  487.                         * * * * * * * * * *
  488.  
  489.  
  490.       Usage: CALL MAP$ ( AIN, AOUT )
  491.  
  492.         AIN    = < byte >
  493.         AOUT   = < byte >
  494.  
  495. Map a lower case character to upper case.
  496.  
  497. If the input character is not a lower case alphabet
  498. character, no mapping takes place.
  499.  
  500. Input Arguments:
  501. AIN ..... The one-byte value to be mapped.
  502.  
  503. Output Arguments:
  504. AOUT .... The one-byte value mapped to u.c.
  505.  
  506.  
  507.  
  508.                         * * * * * * * * * *
  509.                         *                 *
  510.                         *   E R R O R $   *
  511.                         *                 *
  512.                         * * * * * * * * * *
  513.  
  514.  
  515.       Usage: CALL ERROR$ ( NERROR, ANAME, ARRAY )
  516.  
  517.         NERROR = < integer >
  518.         ANAME  = < byte array >
  519.         ARRAY  = < byte array >
  520.  
  521. Error printing routine.
  522.  
  523. Input Arguments:
  524. NERROR ... Number of the error message to print.
  525. ANAME .... A six-byte name for the routine which called
  526.            the error.
  527. ARRAY .... A byte array, the contents of which depend on
  528.            the error being processed.
  529.  
  530. Output Arguments:
  531.     (none)
  532.  
  533.