Function: Point r6 and a2 to the filename that the user entered.
Pass: nozero - set bit 7 of this variable if you do not want a zero placed at the end of the filename, otherwise simply ignore this variable (it is automatically reset to zero when the routine is finished), it is not necessary for your command to set it to zero.
Return: goodflag - set if what appears to be a valid filename was found.
r6 - points to a null terminated filename.
a2 - points to a null terminated filename.
WILDCARD - bit 7 set if any wildcard characters are found (* and/or ?).
r0 - if bit 5 of WILDCARD is set, this means that the user included an equals ( = ) sign somewhere in the parameter and r0 will be pointing at the first null-terminated filename while a2 and r6 will be pointing at the second one.
NUM_IN_NAME - contains the number of characters 1-16 that are in the filename.
Description: Call this routine when your command needs to have a filename follow as a parameter. If ParamName finds what appears to be a valid filename (up to a maximum of 16 characters), it will exit through yesgood. If you find that goodflag does not have bit 7 set, then the routine failed and you do not have any valid filename to process. Handle this accordingly.
When a command needs two filenames entered in a manner such as what the 'rename' command requires, then r0 will return pointing at the first filename and a2 will be pointing at the second.
Example: ren newname=oldname
In this case, both filenames will become null-terminated. You can tell that the user entered a parameter this way by checking bit 5 of WILDCARD. If it is set, then an equals sign was found.
If bit 7 of WILDCARD is set, then the user entered at least one wildcard in the filename. In the case of bit 5 being set, wildcards are only checked in the second filename, the one that a2 is pointing at.
Example:
;this example requires that the user enters two filenames similar
;to the way that the rename command works.
jsr ParamName
bit goodflag
bmi 10$
jsr MissgFilename
bbrf 5,WILDCARD,5$ ;use a macro to test bit 5.
;did the user enter two names?
;it will branch if not.
MoveW r0,firstName ;save r0 for now.
jsr CkPresdrive ;check the current drive
;for the second filename.
bit goodflag ;does the file exist?
bmi 30$ ;branch if so.
jsr NotFound ;tell the user, not found.
jmp NoMoreCmds ;and exit.
MoveW a2,secondName ;save this name for now.
MoveW firstName,a2 ;now let's
jsr CkPresdrive ;look for the first filename.
bit goodflag ;did we find it?
bpl 20$ ;branch if not.
... ;at this point we have
... ;determined that both
... ;filenames exist on the
... ;currently active drive
... ;and we may continue on...
inc NUM_IN_NAME ;get the length of the a2
lda NUM_IN_NAME ;filename plus on for a space.
jsr IncCmdPointer ;point at the next command.
jmp ExitCommand ;and exit cleanly.
firstName:
.block 2
secondName:
.block 2
See Also: FindParName
@PopStuff
Function: Restore certain variables after a call to PushStuff.
Pass: nothing
Return: r0-r15, a0-a4 are restored to the values they held when PushStuff was called.
Destroys: nothing
Description: Refer to PushStuff for the basic purpose of these two routines. Do not call this routine except after you have already called PushStuff, but be sure to call it if you have called PushStuff. PopStuff restores various zero page locations from a special built-in stack that is maintained by geoSHELL. Treat it just like you would if you were to push a byte onto the processor's stack. One difference here though is that if you exit your command through NoMoreCmds, then this built-in stack is reset anyway and you would not need to call PopStuff.
Function: Purge the turbo code from all the drives that are being used in order to perform low-level DOS routines.
Pass: nothing
Return: goodflag - could be either set or cleared, but in the case of this routine, it is meaningless.
Destroys: a, x, y, r0-r3
Description: Before performing any low level functions with the drives such as direct memory accessing, it is necessary to purge the turbo code in the drive so that the disk driver will restore it completely when EnterTurbo is called. If not, then your routines could possibly corrupt the turbo code that is in the drive and the driver would think that it is still intact.
This routine purges the turbo code from 'all' the drives so that you might be able to do low level functions with more than one drive at a time as you wish. geoSHELL's normal disk accessing will tell the disk drivers to restore the needed turbo code before any GEOS disk accessing. For that reason, it is not necessary that your command call EnterTurbo unless it will also need some GEOS disk accesses.
If you are dealing with the DOS in just one drive, then you could just call PurgeTurbo for that one device. However some of the routines that you call in geoSHELL, especially the ones that deal with the CMD devices, might deal with more than one drive and therefore needs the turbo code in all the drives to be purged. This routine will do that for you.
Example:
jsr PurgeAllTurbos ;kill all the turbo code.
jsr InitForIO ;pop out of GEOS.
... ;do some low-level stuff.
jsr DoneWithIO ;pop back into GEOS.
jmp ExitCommand
See Also:
@PushStuff
Function: Save certain zero
@PushStuff
Function: Save certain zero page locations to a built-in stack.
Pass: nothing
Return: nothing
Destroys: nothing
Description: In some cases you might want to preserve the locations from r0-r15. Just call this routine and geoSHELL will save them on a special stack contained in memory. The locations from a0-a4 are also saved with this routine. Nothing gets trashed when calling this routine. a,x and y are not trashed. Use PopStuff to restore all of these locations. If you call PushStuff, be sure to call PopStuff, for the same reason you would do a pla after you do a pha instruction. If you exit your command through NoMoreCmds, this will be done for you.
Since the stack this routine uses is 256 bytes long, and 42 bytes are saved to it each time, you can safely call this routine 6 times before having to call PopStuff. The last set in is the first set out, just like pushing and pulling one byte on the processor's stack.
Example:
;this example looks for a filename on the current drive, and
;whether the file is found or not, it will continue with whatever
;it is designed to do. But while it is displaying a message to the
;user, it will save some stuff and restore afterwards and then
;continue on.
jsr ParamName ;get the filename.
jsr CkPresdrive ;is it on the current drive?
bit goodflag ;well?
bmi 10$ ;branch if so.
jsr PushStuff ;save everything.
jsr NotFound ;tell the user 'not found'.
jsr PopStuff ;restore everything.
... ;and continue...
See Also: PopStuff
@RdFnKeyDefs
Function: Load the default function key definitions from the current drive.
Pass: geoSHELL must be an open VLIR fi
@RdFnKeyDefs
Function: Load the default function key definitions from the current drive.
Pass: geoSHELL must be an open VLIR file.
Return: goodflag - set if geoSHELL was found on the current drive and the function key definitions loaded successfully.
Destroys: a, y, r1-r4, r7
Description: This routine will load in the function key definitions from the currently open drive if there is a copy of geoSHELL on the drive. The user will now have access to those function key definitions. The 'defkey' command uses this routine. You must first open geoSHELL as a VLIR file before calling this routine. Close the file afterwards.
Example:
;here is an example of a complete geoSHELL command that will
;load in the function key definitions from the drive that the
;user chooses. Let's call this command 'loadkeys'. The user is
;supposed to enter the command followed by a parameter that
;specifies the desired drive to load the keys from.
;Example: loadkeys b
;This would load the function key definitions from drive B.
;You'll notice in this source code, that the idea is to keep
;checking for errors to keep the user from crashing his machine.
;Here's the complete source code for the command.
LoadKey:
lda ParamTable+1 ;check that only one
jsr CkTerminators ;character is entered.
bit goodflag
bmi 10$ ;branch if so.
jmp MissgFilename ;(bad parameter)
lda ParamTable+0
jsr CkDrvLetter ;convert this to the
;desired device number (8-11).
bit goodflag ;is it legal?
bpl 5$ ;branch if not.
pha ;save the device number.
LoadW a2,#ShellText ;point a2 at the geoSHELL
;name.
jsr CkThisDrive ;see if geoSHELL is on this
bit goodflag ;drive.
bmi 20$ ;branch if so.
jsr NotFound ;tell the user, not found.
jmp NoMoreCmds ;and exit.
MoveW a2,r0 ;point r0 at the name.
jsr OpenWrFile ;this opens a VLIR file.
bit goodflag ;was it successful?
bmi 30$ ;branch if so.
jmp LoadProblem ;tell about a loading problem.
jsr RdFnKeyDefs ;load in the function keys.
bit goodflag ;did it go OK?
bmi 40$ ;branch if so.
jsr CloseRecordFile ;close the file.
bra 25$ ;and do an error thing.
jsr CloseRecordFile ;close the file.
LoadW r0,#successText ;and tell the user
lda #(IN_TWO|TR_CR) ;that it went OK.
jsr OtherMessage
lda #2
jsr IncCmdPointer ;point at the next command.
jmp ExitCommand ;and exit cleanly.
successText:
.byte "Function Keys Loaded!",0
ShellText:
.byte "geoSHELL",0
See Also:
@ReadChannel
Function: Read a drive's error channel.
Pass: a - device number of desired drive.
InitForIO must be called first.
@ReadChannel
Function: Read a drive's error channel.
Pass: a - device number of desired drive.
InitForIO must be called first.
Return: EnOfShell - up to 256 bytes of information from the drive's error channel.
goodflag - set if the read was successful.
Destroys: a, x, y
Description: This command will read a drive's error channel and return the information to a buffer at EnOfShell. This buffer is 256 bytes long in order to accomodate the number of bytes that may come from a CMD device's error channel as opposed to a CBM device. This routine handles the communication between the computer and the drive for you. If goodflag is set, then you will find some valid bytes in the buffer at EnOfShell, otherwise it may just contain null bytes. So check goodflag first upon return from this routine. Also, before calling this routine, be sure to call PurgeAllTubos and InitForIO.
Example:
lda PRESDRIVE ;do this in case it's an
jsr GetRealDriveNum ;RD or RL as a RAM_1581.
;this also calls PurgeAllTurbos.
jsr InitForIO ;pop out of GEOS.
... ;through here, you might
... ;have some code that
... ;accesses the drive's DOS
... ;for whatever reason.
lda REALDRIVE ;now let's check the
jsr ReadChannel ;error channel.
jsr DoneWithIO ;pop back into GEOS.
bit goodflag ;was the read successful?
bmi 20$ ;branch if so.
jmp DoError ;display some sort of error.
... ;now we can read the data
... ;located at EnOfShell.
See Also: PurgeAllTurbos, SendCmd, SendListen, SendTalk, GetRealDriveNum
@ReDisplayWindow
Function: Clear each line in the geoSHELL window and redisplay the text contained in it fro
@ReDisplayWindow
Function: Clear each line in the geoSHELL window and redisplay the text contained in it from the internal buffers.
Pass: nothing
Return: nothing
Destroys: no guarantees
Description: If your command does anything that might alter the state of what is being displayed in the geoSHELL window, you can use this routine to restore the text as it should be.
Example:
... ;let's say that your command
... ;puts up a couple of icons
... ;in the middle of the geoSHELL
... ;window in this code here.
... ;that would wipe out the text
... ;that was there.
bit goodflag ;did the user do as he should?
bmi 50$ ;branch if so.
jsr ReDisplayWindow ;restore the text in the window.
Function: Redraw the geoSHELL window and any text that was already contained in it.
Pass: nothing
Return: nothing
Destroys: no guarant
@ReDoWindow
Function: Redraw the geoSHELL window and any text that was already contained in it.
Pass: nothing
Return: nothing
Destroys: no guarantees
Description: When your command performs some sort of action that might disrupt the geoSHELL window, call this routine to restore it. The text that is contained in the memory buffer will be restored to the window after the window is redrawn.
Function: Reset a CMD device back from the path partition to the current partition the user
@ResetFromPath
Function: Reset a CMD device back from the path partition to the current partition the user is operating in.
Pass: nothing
Return: nothing
Destroys: no guarantees
Description: After calling any routine that does a file search on a path partition, call this routine to put the drive back to it's proper partition. If you do not, then the drive will remain in the partition that is defined as the path partition if the desired file was found on the path partition. It is up to your command to do this. This way, the path partition can remain open until you are finished with it.
Example:
jsr ParamName ;get the filename.
bit goodflag ;is it valid?
bmi 10$ ;branch if so.
jmp MissgFilename ;do an error message and exit.
jsr CkPath ;check the path partition
bit goodflag ;for the file.
bmi 20$ ;branch if found.
jmp FileNotAvail ;otherwise do a file not
;available error and exit.
... ;do what your command intends
... ;at this point.
jsr ResetFromPath ;restore the original partition.
inc NUM_IN_NAME ;ParamName sets this variable.
lda NUM_IN_NAME
jsr IncCmdPointer ;point to the next command.
jmp ExitCommand ;and exit cleanly.
See Also: CkPresdrive, CkThisDrive, CkOtherDrives, CkPathOrder, CkPath, CkForDisk, FindParName
@ResetScreen
Function: Display a fresh geoSHELL screen in the correct mode.
Pass: nothing
Return: nothi
@ResetScreen
Function: Display a fresh geoSHELL screen in the correct mode.
Pass: nothing
Return: nothing
Destroys: a, x, y, r0-r15
Description: This will completely clear the screen and redraw it fresh in the current mode (40 or 80 columns). The geoSHELL window will be redrawn and the cursor will be positioned to the left side of line one.
Return: otherPressVector - set for mouse positioning of cursor.
Close icon - set to exit to Desktop or the calling interface that geoSHELL was entered from.
Mouse limits - set to default settings.
Destoys: a, x, y, r0-r11
Description: If your command does anything to change the icon status that the GEOS kernal is controlling, or otherPressVector, or the mouse position limits, call this routine to fix the problem. This will inform GEOS that the icon at the upper right of the geoSHELL window is there. Some actions might kill this icon, thereby making it necessary to call this routine before exiting your command. While testing your command, be sure to check the icon by clicking on it to see if it is still active after exiting your command. If not, then add the call to this routine before exiting. If you exit to NoMoreCmds, this will be done for you. It actually does no harm to call this routine before exiting your command even if your command does nothing to change these things.
Example:
jsr R_Icons ;fix the close icon.
jmp ExitCommand ;all done with command.
See Also:
@SaveToREU
Function: Copies geoSHELL and Input driver info to REU.
Pass: nothing
Return: nothing
Destroys: a, x, y, r0-r3
Description: When geoSHELL is activated, it installs itself as the default user interface into the GEOS kernal in place of the Desktop. If the user were to exit to BASIC and then use RBOOT to get back into geoSHELL, the Desktop would then be the default interface. This routine fixes that problem. The same thing would happen if the user were to change input drivers. So, for that reason, the 'install' command calls this routine also. Only the portion of the kernal that contains the needed info for the user interface and the input driver is copied to the GEOS kernal area of the REU. There probably is no reason to use this routine unless your command should affect the input driver in some way, such as a patch would. Then you would want to call this routine to insure the patch would be used in an RBOOT situation.
Should there be no REU, no harm is done since the routine will simply rts if no REU is present.
Example:
See Also:
@save_XY_pos
Function: Save the current values of r1H and r11 into two variab
@save_XY_pos
Function: Save the current values of r1H and r11 into two variables.
Pass: r1H - the current desired pixel location of the cursor.
r11 - the desired horizontal pixel location of the cursor.
Return: cur_X_pos will hold the value that was in r11.
cur_Y_pos will hold the value that was in r1H.
Destroys: a
Description: This routine allows you to bypass geoSHELL's management routines and physically relocate the cursor on the screen, if only temporary. Once your command exits, geoSHELL might again take control and properly place it.
There is really no need to use this routine since most of your needs can be handled through other routines that let geoSHELL handle the text displaying and cursor positioning.
Example:
;this example serves no real purpose other than to show
;how this routine could be used. First r1H and r11 are loaded
;with values that correspond to the upper area of the screen.
;This location is 10 pixels down from the top and 48 pixels
;over from the left side. Then save_XY_pos is used to save
;these values to their proper locations and OtherMessage will
;then print a message at the top of the screen instead of
;in the geoSHELL window.
LoadB r1H,#10
LoadW r11,#48
jsr save_XY_pos
LoadW r0,#upperText
lda #0
jsr OtherMessage
See Also: set_XY_pos
@Searching
Function: Display the 'Searching For Filename' message.
Pass: nosearchm
@Searching
Function: Display the 'Searching For Filename' message.
Pass: nosearchmessage - cleared to zero. (it is normally zero and also is always cleared by this routine)
a2 - null terminated filename to display in the message.
Return: message displayed on screen.
Destroys: no guarantees
Description: This routine merely needs a2 to be pointing at a null-terminated filename, and that filename will be included in a message that will be displayed to the screen, such as, 'Searching For Filename'. This is basically just another internal geoSHELL message that can also be called with the routine, Message. 'Searching For' is message number 2. Usually, the entire line the cursor is currently on will be cleared first before displaying this message. The message will always start on the third character location and perform a carriage return afterwards.
Whenever the routine CkAllDrives is being used to search for a file, this routine is automatically called. So, if you wish the 'Searching For ...' message to be displayed you need not do anything when CkAllDrives is being used. For any other searching function, such as CkThisDrive, you would have to call this routine. If you wish to have CkAllDrives 'not' call this routine, then set the variable nosearchmessage to 128. It is not necessary to reset this variable afterwards since it is automatically reset.
Example:
jsr ParamName ;get the filename.
bit goodflag ;is there one?
bmi 10$ ;branch if so.
jmp MissgFilename ;display error and exit.
jsr Searching ;display searching message.
jsr CkPresdrive ;look on the current drive.
bit goodflag ;did we find the file?
bmi 20$ ;branch if so.
jmp FileNotAvail ;display an error and exit.
... ;continue on...
See Also:
@SendCmd
Function: Send a string of bytes to the drive's command channel.
Pass: a - real device number of desired drive.
r0 - points to the byt
@SendCmd
Function: Send a string of bytes to the drive's command channel.
Pass: a - real device number of desired drive.
r0 - points to the bytes to send.
cmdlength - number of bytes (1-255) to send. A zero here will send 256 bytes.
Be sure to purge the turbo code from the drive that the command is being sent to, and call InitForIO also.
Return: goodflag - set if the drive responded and accepted the bytes.
r0 - unchanged.
Destroys: a, x, y
Description: This routine may be used to send any string of bytes to a drive that is connected to the computer. In fact, it does not have to be one of the drives that GEOS is working with. Just point r0 at the string of bytes, and set cmdlength to the number of bytes you wish to send, load the accumulator with the (real) device number of the desired drive and call this routine.
Don't forget to purge the turbo code in the drive and call InitForIO before calling this routine.
Example:
;this example will send a string to the drive's command channel
;that will cause a drive to initialize the disk.
jsr PurgeAllTurbos ;let's kill all the turbos.
jsr InitForIO ;pop out of GEOS.
LoadW r0,#iText ;point r0 to bytes.
LoadB cmdlength,#2 ;load cmdlength with # of bytes.
lda driveNum ;get the device number.
jsr SendCmd ;send the command.
bit goodflag ;did the drive take it?
bmi 20$ ;branch if so.
jsr DoneWithIO ;pop back into GEOS.
jmp DoError ;do an error of some sort.
... ;continue on...
iText:
.byte "I0" ;initialize command.
ne, then set the variable nosearchmessage to 128. It is not necessary to reset this variable afterwards since it is automatically reset.
Example:
jsr Param
driveNum:
.byte 8 ;drive number stored here.
See Also: PurgeAllTurbos, ReadChannel, SendListen, SendTalk, GetRealDriveNum
@SendList
@SendListen
Function: Get a drive's attention and send it a command.
Pass: a - real device number of desired drive.
cmdtosend - the secondary command byte to send to the drive.
You must purge the turbo code in the drive and call InitForIO before calling this routine.
Return: goodflag - set if device is responding.
the device - still in the 'Listen' mode (if goodflag is set) and will accept more bytes on the serial bus.
Destroys: a
Description: This routine will prepare a drive to receive bytes on the serial bus. After setting up and calling this routine, if goodflag is set, then you may continue to send bytes on the serial bus using the kernal routine, Ciout, and the drive will continue receiving them. Just load cmdtosend with a byte to send as a secondary command and load the accumulator with the device number of the desired drive and call this routine. Then just keep sending bytes through Ciout. When finished, just call the kernal routine Unlsn, and it will tell the drive we are finished sending bytes.
Example:
;this particular example will open a sequential file on the current
;drive so that it's contents may be read into the computer.
jsr ParamName ;get a filename.
bit goodflag ;is it valid?
bmi 10$ ;branch if so.
jmp MissgFilename ;display bad parameter.
lda PRESDRIVE
jsr GetRealDriveNum ;get the real device number.
;this will also purge all turbos.
bit goodflag ;is this a real drive?
bmi 20$ ;branch if so.
LoadW r0,#notRealText ;display an error message,
lda #(IN_TWO|TR_CR)
jsr OtherMessage
jmp NoMoreCmds ;and exit.
jsr InitForIO ;pop out of GEOS.
LoadB cmdtosend,#(3|$f0) ;open channel 3,
lda REALDRIVE ;in this particular device,
jsr SendListen ;attempt to open it.
bit goodflag ;was it successful?
bmi 30$ ;branch if so.
jsr DoneWithIO ;otherwise,
LoadW r0,#notRespText ;do an error message.
lda #(IN_TWO|TR_CR)
jsr OtherMessage
jmp NoMoreCmds ;
bit goodflag ;was it successful?
bmi 30$ ;branch if so.
jsr DoneWithIO ;otherwise,
LoadW r0,#notRespText ;do an error message.
lda #(IN_TWO|TR_CR)
jsr OtherMessage
jmp NoMoreCmds ;and exit.
ldy #0
lda (a2),y ;open the channel with
jsr Ciout ;our filename.
cpy NUM_IN_NAME ;have we sent the whole
;filename?
bne 40$ ;branch if not.
lda #CR ;send a carriage return
jsr Ciout ;to the drive.
jsr Unlsn ;make it do it's thing.
lda REALDRIVE
jsr ReadChannel ;see if it did it's thing.
bit goodflag ;check goodflag first.
bpl 25$
lda EnOfShell+0 ;did the error channel
cmp #'0' ;return '0' in the first byte?
bne 25$ ;branch if not.
cmp EnOfShell+1 ;how about the second byte?
bne 25$ ;branch if not.
LoadB cmdtosend,#(3|$60) ;get the channel ready
lda REALDRIVE ;for reading.
jsr SendTalk
bit goodflag ;is it ready?
bpl 25$ ;branch if not.
LoadW r0,#buffer ;point r0 at our buffer.
LoadB STATUS,#0 ;be sure to clear STATUS.
ldy #0
jsr Acptr ;read a byte from the drive.
sta (r0),y ;store it in our buffer.
iny ;increment for the next byte.
bne 60$
inc r0H
lda r0H ;have we reached the end
cmp #$7f ;of our buffer?
beq 70$ ;branch if so.
lda STATUS ;is this the end of file
;or any other error?
beq 50$ ;branch if not.
jsr Untalk ;stop the drive.
LoadB cmdtosend,#(3|$e0) ;and close the channel.
lda REALDRIVE
jsr SendListen
jsr Unlsn
jsr DoneWithIO ;pop back into GEOS.
... ;at this point, we have
... ;a buffer filled with the
... ;bytes from the file that
... ;the user desired and our
... ;command may continue to do
jsr DoneWithIO ;pop back into GEOS.
... ;at this point, we have
... ;a buffer filled with the
... ;bytes from the file that
... ;the user desired and our
... ;command may continue to do
... ;as it is designed to do.
notRealText:
.byte "This Is Not A REAL Drive!",0
notRespText:
.byte "The Drive Is Not Responding!",0
See Also: PurgeAllTurbos, ReadChannel, SendCmd, SendTalk, GetRealDriveNum
@SendTalk
Function: Get a drive's attention and send it a command to prepare it for talking.
Pass: a - real device number of desired drive.
cmdtosend - the secondary command byte to send to the drive.
You must purge the turbo code in the drive and call InitForIO before calling this routine.
Return: goodflag - set if device is responding.
the device - is in the 'Talk' mode (if goodflag is set) and will send bytes to the computer by using the kernal routine 'Actpr'.
Destroys: a
Description: This routine will prepare a drive to send bytes on the serial bus. After setting up and calling this routine, if goodflag is set, then you may begin receiving bytes on the serial bus using the kernal routine Acptr. Just load cmdtosend with a byte to send as a secondary command and load the accumulator with the device number of the desired drive and call this routine. Then just keep receiving bytes through Acptr until STATUS is any non-zero value. When finished, use the kernal routine Untalk to tell the drive we are finished receiving bytes.
Example: Refer to the example in the description for the routine 'SendListen'. It includes an example of how to use SendTalk.
See Also: PurgeAllTurbos, ReadChannel, SendCmd, SendTalk, GetRealDriveNum
@Send_GC_Byte
Function: Send a byte to a printer via a geoCable connected to the user port.
Pass: a - byte to send.
InitForIO must be called before accessing this routine.
Return: nothing - no er
@Send_GC_Byte
Function: Send a byte to a printer via a geoCable connected to the user port.
Pass: a - byte to send.
InitForIO must be called before accessing this routine.
Return: nothing - no error checking is performed
Destroys: a
Description: This routine will send the byte contained in the accumulator to a parallel printer connected to the user port via a geoCable. No error checking is done. If the routine returns, the byte was sent, and you can send another one if desired. It is a good idea to call Open_GC_Channel before this one to verify the presence of a printer before using this routine. Otherwise, if the printer is not accepting the byte, the routine might just wait until it does so. That could be forever. As long as Open_GC_Channel returns with x=0 then it is OK to use this routine to send data to the printer.
Example:
;this example will send the bytes contained in a buffer to the
;printer. r0 points to the start of the buffer and r2 points to
;the byte just past the end of the buffer. If this example returns
;with goodflag set, the buffer was sent to the printer.
SendBuffer:
jsr InitForIO ;pop out of GEOS.
jsr Open_GC_Channel ;check for a printer.
txa ;check if x = 0.
beq 10$ ;branch if so.
jsr DoneWithIO ;pop back into GEOS.
jmp nogood ;signal calling routine of error.
ldy #0 ;y will stay at zero throughout
;the sending of text.
lda (r0),y ;get a byte from the buffer.
jsr Send_GC_Byte ;send it to the printer.
inc r0L ;point at the next byte.
bne 30$
inc r0H
sec ;have we reached the end?
lda r0L
sbc r2L
lda r0H
sbc r2H
bcc 20$ ;branch if not.
jsr DoneWithIO ;pop back into GEOS.
jmp yesgood ;and te
jsr DoneWithIO ;pop back into GEOS.
jmp yesgood ;and tell the calling routine
;everything went OK.
See Also: Open_GC_Channel
@SetBrdrColor
@SetBrdrColor
Function: Change the color of the 80 column screen's border.
Pass: brdrcolor - color (0-15).
Return: border color changed.
Destroys: a, x, temp_check
Description: This routine will change the color of the 80 column screen's border to the color that is stored in brdrcolor. Your routine must check to be sure that the machine is a 128 before calling this routine. It should also check the videomode to make sure that the computer is not in monochrome mode.
Example:
;this example is a routine that will change the border to blue.
BlueBorder:
bit videomode ;128 in RGB mode?
bmi 10$ ;branch if so.
LoadB brdrcolor,#DK80BLUE
jmp SetBrdrColor ;change the border
;to blue.
See also: ColorScreen, FixColors
@SetDrName
Function: Display drive letter, drive type, and disk name.
Pass: a - desired drive number (8-11) representing drive A-D.
Return: goodflag - meaningless with this ro
@SetDrName
Function: Display drive letter, drive type, and disk name.
Pass: a - desired drive number (8-11) representing drive A-D.
Return: goodflag - meaningless with this routine.
Destroys: no guarantees
Description: Load the accumulator with a device number (8-11) representing any of the available drives or ramdisks and call this routine to display the drive letter, the drive type, and the name of the disk that is in the drive. Both the 'status' and the 'dir' commands call this routine. The status command will call it once for each of the drives that are being used. The line the cursor is on will be cleared before the text is displayed.
Example:
;suppose you wanted to create a command that would display various
;bits of information about a drive and the disk that it contains.
;You could call SetDrName to start with and then test the drive
;and disk to get other bits of info to display.
lda ParamTable+1 ;make sure only one
jsr CkTerminators ;parameter was used for this.
bmi 10$ ;branch if so.
jmp MissgFilename ;display bad parameter.
lda ParamTable+0 ;get the parameter.
jsr CkDrvLetter ;convert it to 8-11.
bit goodflag ;did it convert OK?
bpl 5$ ;branch if not.
jsr SetDrName ;display some stuff.
... ;now we can continue
... ;testing the drive...
See Also: Dir, MissDisk, Status, CkDrvLetter, CkForDisk
@SetPartParams
Function: Set
@SetPartParams
Function: Set up some internal variables for the current partition.
Pass: curdrvtype - Set this variable by calling GetRealDriveNum first.
a - real device number from REALDRIVE after calling GetRealDriveNum.
Return: goodflag - set if a CMD device with partitions.
certain internal variables will contain information about the current partition on the desired device.
Destroys: a, x, y, r0
Description: The main purpose of this routine is to establish the information that geoSHELL needs for the current partition of a particular drive. If you were to open a different partition such as what happens when geoSHELL accesses commands on the path partition, then with this information, the original partition and drive is known so that it may be restored. Until the partition is restored, the routine should not be used again. Once the partition is restored, either through the required call to ResetFromPath, OpenCurPartition, or InitCurPartition, then SetPartParams may be used again in order to set up for another partition to be opened. Even when your command intends to open a partition through a call to OpenPartition, and leave that partition open with no intentions of returning to the original one, this routine still needs to be called. This is because OpenPartition checks to make sure that the desired partition to open is of the same type as the current one so that it is compatible with the disk driver that is being used with GEOS on that drive.
Example: Refer to OpenPartition for an example of how to use this routine.
See Also: InitCurPartition, OpenCurPartition, ResetFromPath, OpenPathPartition, SetPartParams
@SetThisDevice
Function: A substitute for the GEOS rou
@SetThisDevice
Function: A substitute for the GEOS routine 'SetDevice'.
Pass: a - drive number 8-11.
Return: goodflag - set if device is now ready.
x - contains zero or error number if any from GEOS.
Destroys: a, x, y
Description: This routine is a recommended substitute for the GEOS kernal routine 'SetDevice'. During it's execution, it still calls SetDevice, but also does some other checking. It also does a jump through yesgood or nogood for setting goodflag. During geoSHELL development, it was discovered that some disk drivers that are used in GEOS would mysteriously lock up under certain circumstances. This lock up occured while calling SetDevice. The lockup required just the right conditions for it to occur. By calling this routine instead of SetDevice, you will still accomplish the same function but with less chance of any problems occuring under these conditions.
Example:
;this example expects a drive letter from the user following the
;command. After the usual checking of the parameter, SetThisDevice
;is called and the command proceeds to execute.
lda ParamTable+1 ;only one parameter needed.
jsr CkTerminators
bit goodflag
bmi 10$ ;branch if one parameter.
jmp MissgFilename ;display bad parameter.
lda ParamTable+0 ;get the parameter.
jsr CkDrvLetter ;set it to 8-11.
bmi goodflag ;is it 8-11?
bpl 5$ ;branch if not.
jsr SetThisDevice ;Set the Device.
bit goodflag ;everything OK?
bmi 20$ ;branch if so.
LoadW r0,#noDriveText ;do an error message.
lda #(IN_TWO|TR_CR)
jsr OtherMessage
jmp NoMoreCmds ;and exit.
... ;continue on...
noDriveText:
.byte "Drive Not Available!",0
.byte "Drive Not Available!",0
See Also: CkForDisk
@set_XY_pos
Function: Load r1H and r11 with the pixel values of the current cursor position.
Pass: nothin
@set_XY_pos
Function: Load r1H and r11 with the pixel values of the current cursor position.
Pass: nothing
Return: r1H holds the vertical pixel location of the cursor.
r11 holds the horizontal pixel location of the cursor.
Destroys: a
Description: Used by internal geoSHELL routines or your routines if you need to do any manual displaying of text to the screen. Text displaying is normally handled nicely by geoSHELL with other routines, so you rarely would have a need to call this routine.
Example: See save_XY_pos for an example of how to use this routine.
See Also: save_XY_pos
@Status
Function: Display information for each of the connected drives.
Pass: nothing
Return: inf
@Status
Function: Display information for each of the connected drives.
Pass: nothing
Return: information on the screen.
goodflag is meaningless here.
Destroys: no guarantees.
Description: This is the routine that the 'status' command calls. In fact, this is the status command. You can use this if you need to show the drives that are currently online. The swap command calls this to display the arrangement of the drives after it performs the swap.
Example:
jsr Status
See Also: Dir, MissDisk, SetDrName, CkDrvLetter, CkForDisk
Example:
jsr ParamName ;get the filename.
bit goodflag ;is there one?
bmi 10$ ;
@StripRulers
Function: Strip the GeoWrite rulers, escapes and any other unwanted characters from a GeoWrite page loaded into memory.
Pass: r0 - start of null terminated buffer.
r2 - location to save converted buffer to.
Return: buffer stripped, null-terminated, and located where r2 was pointing when the routine was called.
goodflag - affected, but meaningless with this routine.
r2 - points at the zero byte that ends the buffer.
Destroys: a, x, y, r0, r2
Description: This routine will take a GeoWrite page that is loaded into memory and convert in such a way that you will be left with only ASCII text. Load r0 with start of the buffer and r2 with the start of the area to save the converted buffer to. r2 must be less than or equal to r0, or it can point past the end of the buffer that r0 is pointing at. Normally, you would set r2 equal to r0 so that the buffer will remain in the same location. This will strip the GeoWrite rulers, escapes and any other unwanted characters.
The only hitch to this routine is that it was designed for the startup and exec commands. This means that carriage returns and tabs are converted to a single space. In fact, any byte that is less than a 32 or greater than a 126 is converted to a space. For an exec file, this ends up making it basically one long command line. Remember that geoSHELL allows more than one command to be on a line, so it has no use for any carriage returns.
After this routine is called, the only byte in the buffer that will fall outside of 32-126 will be the last one and it will be a zero byte.
Description: This is the routine that the 'switch' command jumps to. In fact, this is the switch command, and will act just as if the user entered the command. If this routine is accessed in 64 mode, the user will be presented with a message stating '128 Only Command' and will promptly jump through NoMoreCmds, thereby ending your command. So, you would want to check screenmode to make sure that the machine is a 128 before using this routine, unless you intend for this to happen.
Example:
;this example is actually the source code for a possible command
;that could be called 'srun'. This will check the screenmode of a file
;before it is loaded, and it will give the user the option of
;switching screens or aborting. The routine CkModeFlag is called in
;this command to check if the file is compatible with the machine.
;The various values that can be returned in x by this routine can
;be found in the appendix.
SRun:
jsr ParamName ;get the filename.
bit goodflag ;was there one?
bmi 20$ ;branch if so.
jmp MissgFilename ;display bad parameter.
jsr CkAllDrives ;look for the file.
bit goodflag ;did we find it?
bmi 20$ ;branch if so.
jmp FileNotAvail ;display not available.
jsr GetHeader ;get the file's header block.
bit goodflag ;is it a GEOS file?
bpl 80$ ;branch if not and then try
;to run it.
jsr CkModeFlag ;see if it's compatible?
bit goodflag ;well?
bmi 80$ ;branch if so and run it.
bit screenmode ;check the mode we're in.
bvs 90$ ;branch if 64 mode (can't run).
;at this point we know that we are running on a 128. All we need
;to check for is if the file is for 64 only. The only other
;possibility would be if we need to switch from 40 to 80 or
;from 80 to 40. So, if not 64 mode, then we can switch screens
;from 80 to 40. So, if not 64 mode, then we can switch screens.
;if x = 36 " is for 40 columns!"
;if x = 37 " is for 128-40 columns!"
;if x = 38 " is for 128-80 columns!"
;if x = 39 " is for 128 mode!"
;if x = 40 " is for 64 mode!"
;if x = 41 " is not a GEOS file!"
cpx #40 ;is the file for 64 only?
beq 90$ ;branch if so (can't run).
txa ;save x for now.
MoveW a2,r0 ;display the filename...
lda #(IN_TWO|TR_ONE) ;stay on the same line...
jsr OtherMessage
txa ;restore x and...
lda #TR_CR
jsr Message ;display the mode the file
;is designed for.
LoadW r0,#switchText ;display a requestor
lda #(IN_TWO|TR_CR) ;to switch screens.
jsr OtherMessage
jsr Wait ;wait for user input.
lda st_KeyData ;get the key that was pressed.
cmp #25 ;was it a 'y'.
;(keycode, not ascii code)
beq 50$ ;branch if so.
jmp NoMoreCmds ;any other key will abort.
jsr Switch ;switch screens.
jmp DoRun ;hand the job over to
;geoSHELL to run the file.
jmp CantRun ;tell the user, no go.
;(this would be your own
;error routine)
switchText:
.byte "Would You Like To Switch Screens? y/n",0
See Also: CkModeFlag, DoRun
@unsetPrompt
@unsetPrompt
Function: Turn the blinking cursor off.
Pass: nothing
Return: cursor is turned off.
Destroys: nothing
Description: If you wish to turn the cursor on, it is a simple matter to do so. Just set bit 7 of cursorOn. But to turn it off requires more work. This routine will do it for you. It has to make sure that the cursor isn't currently in the visible stage with the character under it in reverse video. If so, it will erase the cursor and reverse the character and then it will make sure that it stays off by clearing bit 7 of cursorOn. Of course, you do not need to access this routine unless you have already turned the cursor on for user input of some sort and then wish it turned back off.
If your routine does an rts to have GEOS mainloop handle your input stuff, then you might want to turn the cursor off if you are not working with any text input. Otherwise, you might have a blinking cursor right in the middle of the graphic that you just displayed on the screen while waiting for the user to click on an icon. This would not look good.
Return: st_keyData contains the keycode (not ascii value) of the key that was pressed.
goodflag - meaningless, it is always set by this routine.
Destroys: a, x, y, r3L
Description: This routine is similar to YesKeypress, except that it turns the mouse off while it is waiting for the user to press a key. This prevents the user from being able to click on geoSHELL's close icon, instead of pressing a key.
Example:
jsr Wait ;wait for a keypress with the
;mouse turned off.
... ;continue on...
See Also: NoKeypress, ClrKeyData, CkKeyboard, YesKeypress
@yesgood
Functi
@yesgood
Function: Usually identifies a successful routine.
Pass: nothing
Return: goodflag - bit 7 set.
Destroys: nothing
Description: geoSHELL uses this routine extensively. It and nogood are the universal routines for identifying successes and failures. This routine actually does nothing more than set a flag (goodflag) to give an indication to a calling routine that a success occured. All the calling routine has to do is check goodflag with the bit instruction. It will be minus if yesgood set it. As an example, the routine 'CkForDisk' will jump through yesgood upon exit of the routine if it found a formatted disk in the drive.
It's true that the carry flag or some other form of error checking could have been used, but it's also possible that the x register or the carry flag could change before we are ready to check it. We have more control over how goodflag is affected, and can do some processing before checking it if needed.
Example:
;this particular example will test an 80 character buffer for any
;non-space character. If a non-space character is found, then it
;will return with goodflag set by calling yesgood.
CkNonSpace:
ldx #0
lda charBuffer,x ;get a character from the buffer.
Return: st_keyData contains the keycode (not ascii value) of the key being pressed.
goodflag - always cleared by this routine.
Destroys: a, x, y
Description: Call this routine when you need a keypress from the user. The Commodore keycode value as listed in the 64 or 128 Programmer's Reference Manual will be returned in st_KeyData. This routine will hold the computer indefinitely until a key is pressed. The value in goodflag is meaningless upon return, however be cautious that you pass the correct value to the next routine in your command because goodflag will always be reset to zero by this routine.
Example:
;this example will check for the user to press the spacebar.
;Of course, any other key could also be checked for, or
;all of them.
CkForSpace:
jsr YesKeypress ;wait for the user to
;press a key.
lda st_keyData ;get the keycode of the key
;the user is pressing.
cmp #60 ;is it the spacebar?
beq 10$ ;branch if so.
jmp nogood ;inform the calling routine
;that the spacebar was not
;pressed.
jmp yesgood ;inform the calling routine
;that the spacebar was
;pressed.
See Also: NoKeypress, ClrKeyData, CkKeyboard, Wait
@-- NOTES --
The geoSHELL Programmer's Development Package 2-PAGE
een used, but it's also possible that the x register or
@-- NOTES --
The geoSHELL Programmer's Development Package 2-PAGE
een used, but it's also possible that the x register or the carry flag could change before we are ready to check it.
The geoSHELL Programmer's Development Package 2-PAGE
(.txt)