Close DOS File

'''Close DOS File Handle'''

'''Syntax:'''
  DOSMS(AX-value,BX-value,CX-value,DX-value) EXCP=statement-label  
'''Entry:'''
  AX-value = "@3E00@"
  BX-value = file handle (from previous open)
  CX-value = "@0000@"
  DX-value = "@0000@"

'''Return:''' 
If an exception occurs, byte 2 of the AX field will contain the DOS error code (in hex).

 
'''Discussion:'''
The DOSMS function call can be used to close a currently open DOS file.<br> This call requires the file's handle, a value assigned when the file is opened.<br> 
Other parameters include an AX-value of "@3E00@" and CX and DX values of null. 

After the call is executed, the file will be closed. As noted earlier, it is the responsibility of the programmer to ensure that any file handles opened are closed upon completion of the desired function. Failure to comply will result in degradation of system performance and possible system hangs. 
 
'''Example:'''
  ! S SFCLOSE,DSK
  ! O FCLOSE,DSK
  ! L T00,E
  ! R QMONITOR
  !
  !==========  CLOSE DOS FILE HANDLE ==============================
  !
  LENGTH 2 & LOCAL AX$,BX$,CX$,DX$        ! Define registers
             LOCAL FILEHANDLE$            ! Define file handle
  LENGTH 64 & LOCAL FILENAME$             ! Define file name
  !
  LENGTH  3 & LOCAL DOSCODE$              ! Define DOS error code
  LENGTH 37 & LOCAL DOSMESSAGE$           ! Define DOS message
  !
  100 FORMAT (ET)                         ! Screen format
  !
  1000 FORMAT DOSMESSAGE$                 ! File input format
  !
  CLEAR                                   ! Initialize variables
  PRINT (0,100)                           ! Set typewriter mode
  !
  PRINT (0) "ENTER FILENAME TO OPEN:"     ! Display prompt
  INPUT (0) FILENAME$                     ! Enter file name
  IF FILENAME$ = "" THEN RUN "QMONITOR"   ! If null, then stop
  FILENAME$ = FILENAME$ + "@00@"          ! Add null byte to name
  !
  AX$ = "@3D42@"                          ! Set AX to "OPEN FILE"
  CX$ = "@0000@"                          ! Set CX to null
  !
  DOSFC(AX$,CX$,FILENAME$) EXCP=BRANCH1   ! Perform DOSFC call
  !
  FILEHANDLE$ = AX$                       ! Save file handle
  !
  PRINT (0) FILENAME$;" OPENED SUCCESSFULLY."
  PRINT (0) "PRESS ENTER TO CLOSE THE FILE."
  INPUT (0) ""
  !
  AX$ = "@3E00@"                          ! Set AX to "CLOSE FILE"
  BX$ = FILEHANDLE$                       ! Set BX to file handle
  CX$ = "@0000@"                          ! Set CX to null
  DX$ = "@0000@"                          ! Set DX to null
  !
  DOSMS(AX$,BX$,CX$,DX$) EXCP=BRANCH2     ! Perform DOSMS call
  !
  PRINT (0) FILENAME$;" CLOSED SUCCESSFULLY."
  PRINT (0) "PRESS ENTER TO STOP."
  INPUT (0) ""
  RUN "QMONITOR"
  !
  BRANCH1:                                ! Exception routine 1
  PRINT (0) "FILE NOT OPENED."            ! Display message
  OPEN (1) "QERCOMET"                     ! Open error file
  DOSCODE$ = "D" + HEXASC(SUB(AX$,2,1))   ! Construct key to file
  READ (1,1000) KEY=DOSCODE$              ! Read error record
  PRINT (0) "DOS error code: ";DOSCODE$   ! Display DOS error code
  PRINT (0) DOSMESSAGE$                   ! Display error message
  INPUT (0) ""                            ! Hold
  CLOSE (1)                               ! Close error file
  RUN "QMONITOR"                          ! Exit
  !
  BRANCH2:                                ! Exception routine 2
  PRINT (0) "FILE NOT CLOSED."            ! Display message
  OPEN (1) "QERCOMET"                     ! Open error file
  DOSCODE$ = "D" + HEXASC(SUB(AX$,2,1))   ! Construct key to file
  READ (1,1000) KEY=DOSCODE$              ! Read error record
  PRINT (0) "DOS error code: ";DOSCODE$   ! Display DOS error code
  PRINT (0) DOSMESSAGE$                   ! Display error message
  INPUT (0) ""                            ! Hold
  CLOSE (1)                               ! Close error file
  RUN "QMONITOR"                          ! Exit
  END