Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.sys.apple2.programmer > #5368 > unrolled thread

Getting started with ORCA/M and IIGS programming

Back to article view | Back to comp.sys.apple2.programmer

Contents

  Getting started with ORCA/M and IIGS programming James Kruth <james@kruth.org> - 2020-01-18 00:32 -0500
    Re: Getting started with ORCA/M and IIGS programming spectrumdaddy@nospam.com (Ewen) - 2020-01-18 07:51 +0000
      Re: Getting started with ORCA/M and IIGS programming James Kruth <james@kruth.org> - 2020-01-20 01:41 -0500
    Re: Getting started with ORCA/M and IIGS programming Andy McFadden <thefadden@gmail.com> - 2020-01-18 07:42 -0800
      Re: Getting started with ORCA/M and IIGS programming James Kruth <james@kruth.org> - 2020-01-20 01:44 -0500
    Re: Getting started with ORCA/M and IIGS programming Stephen Heumann <stephen.heumann@gmail.com> - 2020-01-18 11:01 -0600
      Re: Getting started with ORCA/M and IIGS programming James Kruth <james@kruth.org> - 2020-01-20 02:11 -0500
        Re: Getting started with ORCA/M and IIGS programming spectrumdaddy@nospam.com (Ewen) - 2020-01-20 07:45 +0000
        Re: Getting started with ORCA/M and IIGS programming kelvin@pro-kegs.uucp (Kelvin Sherlock) - 2020-01-20 23:21 -0500
          Re: Getting started with ORCA/M and IIGS programming James Kruth <james@kruth.org> - 2020-01-26 00:25 -0500

#5368 — Getting started with ORCA/M and IIGS programming

Howdy!

I'm interested in writing some text based IIGS programs, mainly to
experiment with the MIDI capabilities of the IIGS. I have some
experience doing small 8-bit programs with Merlin, but this is my first
foray into doing anything with the IIGS toolbox.

I ended up buying a copy of all the byteworks tools from juiced.gs and
now I'm going through the process of slowly learning how to use ORCA/M,
but seemingly right away, I ran into a problem. In the manual on page 3
there's a Hello World program listed as such:

                keep    Hello
                mcopy   Hello.Macros
     Main       start
                phk
                plb
                puts    #'Hello world!',cr=t
                lda     #0
                rtl
                end

This compiles and links just fine using the instructions in the manual,
but produces no output. Further example programs in the manual seem to
have the same problem. Now I noticed that the example program on the
disk has a few extra calls that aren't mentioned in the manual:

                jsl     SystemEnvironmentInit
                jsl     SysIOStartup
                puts    #'Hello world.',cr=t
                jsl     SysIOShutDown

So now I have a few questions. Is there a reference for these system
calls? Why are they left out of the manual? How does ORCA/M know how to
resolve these symbols?

As if that wasn't enough I started looking for other books on IIGS
assembly programming and found that the following code prints something
without all the extra calls:

                pea     testmsg|-16
                pea     testmsg
                ldx     #$200c
                jsl     $E10000

     testmsg    dc      c'Hello world.',h'00'

I understand that this is making a toolbox call to WriteCString and I've
also read that it should have probably called TextStartUp ($020c) first.
What I'm wondering is why the puts ORCA macro is making me do so much
more work than this relatively simple bit of code.

Thanks in advance for you advice and experience!

- James

[toc] | [next] | [standalone]

#5369

James,

> I'm interested in writing some text based IIGS programs, mainly to
> experiment with the MIDI capabilities of the IIGS. I have some
> experience doing small 8-bit programs with Merlin, but this is my first
> foray into doing anything with the IIGS toolbox.
> 
> I ended up buying a copy of all the byteworks tools from juiced.gs and
> now I'm going through the process of slowly learning how to use ORCA/M,
> but seemingly right away, I ran into a problem. In the manual on page 3
> there's a Hello World program listed as such:

Have you got copies of the Addison Wesley IIGS Tollbox Reference Volumes
1-3? If you are doing any serious programming with the IIgs, you will
need those so you can set up the Toolbox calls correctly. You might also
find the Addison Wesley IIGS Introduction to Programming useful as well.

There are many ways to achieve most things when programming at assembly
level using the Toolbox, hence the differences you saw in the examples
you found.

Cheers - Ewen

[toc] | [prev] | [next] | [standalone]

#5374

Ewen,

> Have you got copies of the Addison Wesley IIGS Tollbox Reference Volumes
> 1-3? If you are doing any serious programming with the IIgs, you will
> need those so you can set up the Toolbox calls correctly. You might also
> find the Addison Wesley IIGS Introduction to Programming useful as well.

Thanks for the suggestion. I've gotten PDFs from archive.org and have
been looking over the various toolsets available.

- James

[toc] | [prev] | [next] | [standalone]

#5370

On Friday, January 17, 2020 at 9:32:33 PM UTC-8, James Kruth wrote:
> Now I noticed that the example program on the
> disk has a few extra calls that aren't mentioned in the manual:
> 
>                 jsl     SystemEnvironmentInit
>                 jsl     SysIOStartup
>                 puts    #'Hello world.',cr=t
>                 jsl     SysIOShutDown
> 
> So now I have a few questions. Is there a reference for these system
> calls? Why are they left out of the manual? How does ORCA/M know how to
> resolve these symbols?

Sounds like a run-time library; those aren't system calls.  The direct toolbox version would look more like:

           _TLStartUp                     ;start tool locator

           pea   $0000
           _MMStartUp                     ;start memory manager
           bcs   Crash
           pla
           sta   >UserID

  ; start up misc/math/text tools
           _MTStartUp
           _IMStartUp
           _TextStartUp


I'm guessing "puts" is a macro... do you see it in Hello.Macros?  (It's been a while since I've done this.)

[toc] | [prev] | [next] | [standalone]

#5375

Andy,

> Sounds like a run-time library; those aren't system calls. The direct
> toolbox version would look more like:
>
>            _TLStartUp                     ;start tool locator
>
>            pea   $0000
>            _MMStartUp                     ;start memory manager
>            bcs   Crash
>            pla
>            sta   >UserID
>
>   ; start up misc/math/text tools
>            _MTStartUp
>            _IMStartUp
>            _TextStartUp
>
>
> I'm guessing "puts" is a macro... do you see it in Hello.Macros? (It's
> been a while since I've done this.)

puts is a macro - apparently the manual is a bit out of date. I do
really appreciate the sample startup code you shared! Thanks!

- James

[toc] | [prev] | [next] | [standalone]

#5371

On 2020-01-18 05:32:30 +0000, James Kruth said:
> Now I noticed that the example program on the
> disk has a few extra calls that aren't mentioned in the manual:
> 
>                 jsl     SystemEnvironmentInit
>                 jsl     SysIOStartup
>                 puts    #'Hello world.',cr=t
>                 jsl     SysIOShutDown
> 
> So now I have a few questions. Is there a reference for these system
> calls? Why are they left out of the manual? How does ORCA/M know how to
> resolve these symbols?

The ORCA/M I/O macros like puts are using I/O library functions 
supplied with ORCA/M, and in order for those to work right in the 
latest version of ORCA/M, you need to make startup/shutdown calls like 
you noted in the example program.

This isn't documented in the manual because the manual was written for 
a slightly older version of ORCA/M where these calls weren't needed.  
There should be an Asm65816.Notes file in the Release.Notes directory 
of a standard ORCA/M installation, which contains updates to the manual 
including the documentation for these functions.

> As if that wasn't enough I started looking for other books on IIGS
> assembly programming and found that the following code prints something
> without all the extra calls:
> 
>                 pea     testmsg|-16
>                 pea     testmsg
>                 ldx     #$200c
>                 jsl     $E10000
> 
>      testmsg    dc      c'Hello world.',h'00'

> I understand that this is making a toolbox call to WriteCString and I've
> also read that it should have probably called TextStartUp ($020c) first.
> What I'm wondering is why the puts ORCA macro is making me do so much
> more work than this relatively simple bit of code.

This approach is directly calling the Text Tools, which is part of the 
Apple IIGS Toolbox rather than part of the ORCA libraries.  If you do 
this you don't need to do the ORCA library initialization, but you 
should appropriately start up and shut down the tools you are using.

-- 
Stephen Heumann

[toc] | [prev] | [next] | [standalone]

#5376

Stephen Heumann <stephen.heumann@gmail.com> writes:
> The ORCA/M I/O macros like puts are using I/O library functions
> supplied with ORCA/M, and in order for those to work right in the
> latest version of ORCA/M, you need to make startup/shutdown calls like
> you noted in the example program.
>
> This isn't documented in the manual because the manual was written for
> a slightly older version of ORCA/M where these calls weren't needed.
> There should be an Asm65816.Notes file in the Release.Notes directory
> of a standard ORCA/M installation, which contains updates to the
> manual including the documentation for these functions.

Thank you so much for pointing this out - you're exactly right. I never
thought to look at the release notes.

>> As if that wasn't enough I started looking for other books on IIGS
>> assembly programming and found that the following code prints something
>> without all the extra calls:
>>
>>                 pea     testmsg|-16
>>                 pea     testmsg
>>                 ldx     #$200c
>>                 jsl     $E10000
>>
>>      testmsg    dc      c'Hello world.',h'00'
>>
>> I understand that this is making a toolbox call to WriteCString and I've
>> also read that it should have probably called TextStartUp ($020c) first.
>> What I'm wondering is why the puts ORCA macro is making me do so much
>> more work than this relatively simple bit of code.
>
> This approach is directly calling the Text Tools, which is part of the
> Apple IIGS Toolbox rather than part of the ORCA libraries.  If you do
> this you don't need to do the ORCA library initialization, but you
> should appropriately start up and shut down the tools you are using.

I've done more reading on the Text Tools and one thing I didn't see was
a way to position text on the 80 column screen. It seems like there
aren't toolbox commands to do this. If I want to create a text based
interface do I have to put values in memory directly if I'm running in
native mode? Thanks!

- James

[toc] | [prev] | [next] | [standalone]

#5377

James,

> I've done more reading on the Text Tools and one thing I didn't see was
> a way to position text on the 80 column screen. It seems like there
> aren't toolbox commands to do this. If I want to create a text based
> interface do I have to put values in memory directly if I'm running in
> native mode? Thanks!

You either place the text directly in memory, or use ASCII cursor
commands to move the cursor where you want in the text. The four basic
ones are Ctrl H (backspace), Ctrl U (forward space), Ctrl M (Return),
and Ctrl J (line feed).

For instance, if you were to go to a BBS sending you a VT100 display,
you would find embeded in the text cursor commands that draws the
screen.

Cheers - Ewen

[toc] | [prev] | [next] | [standalone]

#5378

The GS/OS .CONSOLE driver (documented in the GS/OS reference) is another
method for dealing with text interfaces.  It has control codes for
positioning the cursor, etc.

>I've done more reading on the Text Tools and one thing I didn't see was
>a way to position text on the 80 column screen. It seems like there
>aren't toolbox commands to do this. If I want to create a text based
>interface do I have to put values in memory directly if I'm running in
>native mode? Thanks!
>
>- James

-------
ProLine: kelvin@pro-kegs

[toc] | [prev] | [next] | [standalone]

#5389

kelvin@pro-kegs.uucp (Kelvin Sherlock) writes:
> The GS/OS .CONSOLE driver (documented in the GS/OS reference) is another
> method for dealing with text interfaces.  It has control codes for
> positioning the cursor, etc.

Thank you for pointing that out! It looks like exactly what I'm looking
for!

- James

[toc] | [prev] | [standalone]

Back to top | Article view | comp.sys.apple2.programmer

csiph-web