TweetFollow Us on Twitter


Demonstration Program SysMemRes

Goto Contents

// *******************************************************************************************
// SysMemRes.c
// *******************************************************************************************
// This program:
// o  Loads a window template ('WIND') resource and creates a window.
// o  Allocates a relocatable block in the application's heap, gets its size in bytes, draws
//    the size in the window, and then disposes of the block.
// o  Loads a purgeable 'PICT' resource and a non-purgeable 'STR ' resource and draws them in
//    the window.
// o  Checks if any error codes were generated as a result of calls to Memory Manager and
//    Resource Manager functions.
// o  Terminates when the mouse button is clicked.
// The program utilises the following resources:
// o  A 'plst' resource.
// o  A 'WIND' resource (purgeable).
// o  A 'PICT' resource (purgeable).
// o  A 'STR ' resource (non-purgeable).
// *******************************************************************************************

// .................................................................................. includes

#include <Carbon.h>

// ................................................................................... defines

#define rWindowResourceID  128
#define rStringResourceID  128
#define rPictureResourceID 128

// ....................................................................... function prototypes

void  main            (void);
void  doPreliminaries (void);
void  doNewWindow     (void);
void  doMemory        (void);
void  doResources     (void);

// ************************************************************************************** main

void  main(void)



// *************************************************************************** doPreliminaries

void  doPreliminaries(void)

// ******************************************************************************* doNewWindow

void  doNewWindow(void)
  WindowRef windowRef;

  windowRef = GetNewCWindow(rWindowResourceID,NULL,(WindowRef) -1);
  if(windowRef == NULL)


// ********************************************************************************** doMemory

void  doMemory(void)
  Handle theHdl;
  Size   blockSize;
  OSErr  memoryError;
  Str255 theString;
  theHdl = NewHandle(1024);
  if(theHdl != NULL)
    blockSize = GetHandleSize(theHdl);

  memoryError = MemError();
  if(memoryError == noErr)
    DrawString("\pBlock Size (Bytes) = ");

    DrawString("\pNo Memory Manager errors");

// ******************************************************************************* doResources

void  doResources(void)
  PicHandle    pictureHdl;
  StringHandle stringHdl;
  Rect         pictureRect;
  OSErr        resourceError;

  pictureHdl = GetPicture(rPictureResourceID);
  if(pictureHdl == NULL)


  HNoPurge((Handle) pictureHdl);
  HPurge((Handle) pictureHdl);

  stringHdl = GetString(rStringResourceID);
  if(stringHdl == NULL)


  ReleaseResource((Handle) pictureHdl);
  ReleaseResource((Handle) stringHdl);

  resourceError = ResError();
  if(resourceError == noErr)
    DrawString("\pNo Resource Manager errors");

// *******************************************************************************************

Demonstration Program SysMemRes Comments

The 'plst' (Property List) Resource

As stated in the listing, one of the resources utilised by the program is a 'plst' 
(property list) resource.  Carbon applications must contain a 'plst' resource 
with ID 0 in order for the Mac OS X Launch Services Manager to recognize them as Carbon 
applications.  If the 'plst' resource is not provided, the application will be launched as a 
Classic application.

The 'plst' resource used is actually an empty 'plst' resource.  As will be seen at Chapter 9,
 however, this resource, apart from causing Mac OS X to recognise applications as Carbon 
applications, also allows applications to provide information about themselves to the Mac 
OS X Finder.


Carbon greatly simplifies the matter of determining which Universal Headers files need to 
be included in this section.  All that is required is to include the header file Carbon.h, 
which itself causes a great many header files to be included.  If Carbon.h is not specified, 
the following header files would need to be included, and for the reasons indicated:

Appearance.h  Constant:  kThemeSystemFont

              Appearance.h itself includes MacTypes.h, which contains:

              Data Types:  SInt16  Str255  Size  OSErr  Handle  Rect  StringHandle
              Constants:   noErr  NULL

              Appearance.h also includes MacWindows.h, which contains:

              Prototypes:  GetNewCWindow  GetWindowPort

              MacWindows.h itself includes Events.h, which contains:

              Prototype:  Button

              MacWindows.h also includes Menus.h, which itself includes Processes.h, which

              Prototype:  ExitToShell

              Appearance.h also includes QuickDraw.h, which contains:

              Prototypes:  InitCursor  SetPortWindowPort  SetRect  DrawPicture  MoveTo
              Data Types:  WindowRef  PicHandle

              QuickDraw.h itself includes QuickDrawText.h, which contains:

              Prototypes:  TextFont  DrawString

MacMemory.h   Prototypes:  NewHandle  DisposeHandle  GetHandleSize  HNoPurge  HPurge  
                           MemError  MoreMasterPointers

Resources.h   Prototypes:  ReleaseResource  ResError

Sound.h       Prototype:  SysBeep

TextUtils.h   Prototype:  GetString

              TextUtils.h itself includes NumberFormatting.h, which contains:

              Prototypes:  NumToString

It would be a good idea to peruse the header files MacMemory.h and Resources.h at this stage. 
Another header file which should be perused early in the piece is MacTypes.h.


Constants are established for the resource IDs of the 'WIND', 'PICT' and 'STR ' resources.


The main function calls the functions that perform certain preliminaries common to most
applications, create a window, allocate and dispose of a relocatable memory block, and draw a
picture and text in the window.  It then waits for a button click before terminating the

The call to the QuickDraw function QDFlushPortBuffer is ignored when the program is run on Mac
OS 8/9.  It is required on Mac OS X because Mac OS X windows are double-buffered.  (The picture
and text are drawn in a buffer and, in this program, the buffer has to be flushed to the screen
by calling QDFlushPortBuffer.)  This is explained in more detail at Chapter 4.


The call to MoreMasterPointers is ignored when the program is run on Mac OS X.  (Master
pointers do not need to be pre-allocated, or their number optimised, in the Mac OS X memory

On Mac OS 8/9, the call to MoreMasterPointers to allocate additional master pointers is really
not required in this simple program because the system automatically allocates one block of
master pointers at application launch.  However, in larger applications where more than 64
master pointers are required, the call to MoreMasterPointers should be made here so that all
master pointer (nonrelocatable) blocks are located at the bottom of the heap.  This will assist
in preventing heap fragmentation.  Note that specifying a number less than 32 in the inCount
parameter will result in 32 master pointers in the allocated block.

The call to InitCursor sets the cursor shape to the standard arrow cursor and sets the cursor
level to 0, making it visible.


doNewWindow creates a window.

The call to GetNewCWindow creates a window using the 'WIND' template resource specified in the
first parameter.  The type, size, location, title, and visibility of the window are all
established by the 'WIND' resource.  The third parameter tells the Window Manager to open the
window in front of all other windows.  

Recall that, as soon as the data from the 'WIND' template resource is copied to the opaque data
structure known as a window object during the creation of the window, the relocatable block
occupied by the template will automatically be marked as purgeable.

The call to SetPortWindowPort makes the new window's graphics port the current port for drawing
operations.  The call to the Appearance Manager function UseThemeFont sets the font for that
port to the system font.


doMemory allocates a relocatable block of memory, gets the size of that block and draws it
in the window (or, more accurately, in the window's graphics port), and checks for memory

The call to NewHandle allocates a relocatable block of 1024 bytes.  The call to GetHandleSize
returns the size of the allocated area available for data storage (1024 bytes).  (The actual
memory used by a relocatable block includes a block header and up to 12 bytes of filler.)

The call to MemError returns the error code of the most recent call to the Memory Manager.  If
no error occurred, the size returned by GetHandleSize is drawn in the window, together with a
message to the effect that MemError returned no error.  DisposeHandle is then called to free up
the memory occupied by the relocatable block.

MoveTo moves a "graphics pen" to the specified horizontal and vertical coordinates.  DrawString
draws the specified string at that location.  NumToString creates a string of decimal digits
representing the value of a 32-bit signed integer.  These calls are incidental to the


doResources draws a picture and some text strings in the window.

GetPicture reads in the 'PICT' resource corresponding to the ID specified in the GetPicture
call.  If the call is not successful, the system alert sound is played and the program

The SetRect call assigns values to the left, top, right and bottom fields of a Rect variable. 
This Rect is required for a later call to DrawPicture.

The basic rules applying to the use of purgeable resources are to load it, immediately make it
unpurgeable, use it immediately, and immediately make it purgeable.  Accordingly, the HNoPurge
call makes the relocatable block occupied by the resource unpurgeable, the DrawPicture call
draws the picture in the window's graphics port, and the HPurge call makes the relocatable
block purgeable again.  Note that, because HNoPurge and HPurge expect a parameter of type
Handle, pictureHdl (a variable of type PicHandle) must be cast to a variable of type Handle.

GetString then reads in the specified 'STR ' resource.  Once again, if the call is not
successful, the system alert sound is played and the program terminates.  MoveTo moves the
graphics "pen" to an appropriate position before DrawString draws the string in the window's
graphics port.  (Since the 'STR ' resource, unlike the 'PICT' resource, does not have the
purgeable bit set, there is no requirement to take the precaution of a call to HNoPurge in this

Note the parameter in the call to DrawString.  stringHdl, like any handle, is a pointer to a
pointer.  It contains the address of a master pointer which, in turn, contains the address of
the data.  Dereferencing the handle once, therefore, get the required parameter for DrawString,
which is a pointer to a string.

The calls to ReleaseResource release the 'PICT' and 'STR ' resources.  These calls release the
memory occupied by the resources and set the associated handles in the resource map in memory
to NULL.

The ResError call returns the error code of the most recent resource-related operation.  If the
call returns noErr (indicating that no error occurred as a result of the most recent call by a
Resource Manager function), some advisory text is drawn in the window.

The next six lines examine the result of the most recent call to a memory manager function and
draw some advisory text if no error occurred as a result of that call.

Note that the last two calls to DrawString utilise "hard-coded" strings.  This sort of thing is
discouraged in the Macintosh programming environment.  Such strings should ordinarily be stored
in a 'STR#' (string list) resource rather than hard-coded into the source code.  The \p token
causes the compiler to compile these strings as Pascal strings.


As stated in the Preface, when it comes to the system software, the ghost of
the Pascal language forever haunts the C programmer.  For example, a great many system 
software functions take Pascal strings as a required parameter, and some functions 
return Pascal strings.

Pascal and C strings differ in their formats.  A C string comprises the characters 
followed by a terminating 0 (or NULL byte):

| M | Y |   | S | T | R | I | N | G | 0 |

A C string is thus said to be "null-terminated".

In a Pascal string, the first byte contains the length of the string, and the 
characters follow that byte:

| 9 | M | Y |   | S | T | R | I | N | G |

Not surprisingly, then, Pascal strings are often referred to as "length-prefixed" 

In Chapter 3, you will encounter the data type Str255.  Str255 is the C name for a 
Pascal-style string capable of holding up to 255 characters.  As you would expect, 
the first byte of a Str255 holds the length of the string and the following bytes hold 
the characters of the string.

Utilizing 256 bytes for a string will simply waste memory in many cases.  Accordingly, 
the header file Types.h defines the additional types Str63, Str32, Str31, Str27, 
and Str15, as well as the Str255 type:-

    typedef unsigned char Str255[256];
    typedef unsigned char Str63[64];
    typedef unsigned char Str32[33];
    typedef unsigned char Str31[32];
    typedef unsigned char Str27[28];
    typedef unsigned char Str15[16];
Note, then, that a variable of type Str255 holds the address of an array of 256 elements,
each element being one byte long.

As an aside, in some cases you may want to use C strings, and use standard C library 
functions such as strlen, strcpy, etc., to manipulate them.  Accordingly, be aware that 
functions exist (C2PStr, P2CStr) to convert a string from one format to the other.

You may wish to make a "working" copy of the SysMemRes demonstration program file 
package and, using the working copy of the source code file SysMemRes.c, replace the
function doResources with the following, compile-link-run, and note the way the
second and third strings appear in the window.

    void  doResources(void)
      Str255  string1 = "\pIs this a Pascal string I see before me?";
      Str255  string2 = "Is this a Pascal string I see before me?";
      Str255  string3 = "%s this a Pascal string I see before me?";
      Str255  string4;
      SInt16  a;

      // Draw string1    


      // Change the length byte of string1 and redraw

      string1[0] = (char) 23;

      // Leave the \p token out at your peril
      // I (ASCII code 73) is now interpreted as the length byte


      // More peril:-  % (ASCII code 37) is now the length byte


      // A hand-built Pascal string

        string4[a] = (char) a + 64;

      string4[0] = (char) 26;


      // But is there a Mac OS function to draw the C strings correctly?

      DrawText(string2,0,40);  // Look it up in your on-line reference


In the Carbon era, no discussion of strings would be complete without reference to
Unicode and CFString objects.

Preamble - Writing Systems, Character Sets, and Character Encoding A writing system (eg., Roman, Hebrew, Arabic) comprises a set of characters and the basic rules for using those characters in creating a visual depiction of a language. An individual character is a symbolic representation of an element of a writing system. In memory, an individual character is stored as a character code, a numeric value that defines that particular character. One byte is commonly used to store a single character code, which allows for a character set of 256 characters maximum. A total of 256 numeric values is, of course, quite inadequate to provide for all the characters in all the world's writing systems, meaning that different character sets must be used for different writing systems. In one-byte encoding systems, therefore, these different character sets are said to "overlap". As an aside, the Apple Standard Roman character set (an extended version of the 128-character ASCII character set) is the fundamental character set for the Macintosh computer. To view the printable characters in this set, replace the main function in the SysMemRes demonstration program with the following: void main(void) { WindowRef windowRef; SInt16 fontNum, a,b; UInt8 characterCode = 0; doPreliminaries(); windowRef = GetNewCWindow(rWindowResourceID,NULL,(WindowPtr) -1); SetPortWindowPort(windowRef); GetFNum("\pGeneva",&fontNum); TextFont(fontNum); for(a = 0;a < 256;a += 16) { for(b=0;b<16;b++) { MoveTo((a * 1.5) + 60,(b * 15) + 40); DrawText((Ptr) &characterCode,0,1); characterCode++; } } while(!Button()) ; } In addition to the overlapping of character sets between writing systems, a further problem is conflicting character encodings within a single writing system. For an example of this in the Roman writing system, change "\pGeneva" to "\pSymbol" in the above substitute main function.

Unicode Unicode is an international standard that combines all the characters for all commonly used writing systems into a single character set. It uses 16 bits per character, allowing for a character set of up to 65,535 characters. With Unicode, therefore, the character sets of separate writing systems do not overlap. In addition, Unicode eliminates the problem of conflicting character encodings within a single writing system, such as that between the Roman character codes and the codes of the symbols in the Symbol font (see above). Unicode makes it possible to develop and localize a single version of an application for users who speak most of the world's written languages, including Cyrillic, Arabic, Chinese, and Japanese.

Core Foundation's String Services Core Foundation is a component of the system software. Through its String Services, Core Foundation facilitates easy and consistent internationalization of applications. The essential part of this support is an opaque data type (CFString). A CFString "object" represents a string as an array of 16bit Unicode characters. Several Control Manager, Dialog Manager, Window Manager, Menu Manager, and Carbon Printing Manager functions utilize CFStrings. CFString objects come in immutable and mutable variants. Mutable strings may be manipulated by appending string data to them, inserting and deleting characters, and padding and trimming characters. CFStrings have many associated functions that do expected things with strings such as comparing, inserting, and appending. Functions are also available to convert Unicode strings (that is, CFStrings) to and from other encodings, particularly 8bit encodings (such as the Apple Standard Roman character encoding) stored as Pascal and C strings.

Example For a basic example of the use of CFStrings, remove the calls to doMemory and doResources, and the functions themselves, from the main function in the original version of the demonstration program SysMemRes and replace the function doNewWindow with the following: void doNewWindow(void) { WindowRef windowRef; Str255 pascalString = "\pThis window title was set using a CFString object"; CFStringRef titleStringRef; CFStringRef textStringRef = CFSTR("A CFString object converted to a Str255"); Boolean result; Str255 textString; windowRef = GetNewCWindow(rWindowResourceID,NULL,(WindowPtr) -1); SetPortWindowPort(windowRef); UseThemeFont(kThemeSystemFont,smSystemScript); titleStringRef = CFStringCreateWithPascalString(NULL,pascalString, CFStringGetSystemEncoding()); SetWindowTitleWithCFString(windowRef,titleStringRef); result = CFStringGetPascalString(textStringRef,textString,256, CFStringGetSystemEncoding()); if(result) { MoveTo(135,130); DrawString(textString); } if(titleStringRef != NULL) CFRelease(titleStringRef); } At the sixth line, an immutable CFString object is created. The easiest way to do this is to use the CFSTR macro. The argument of the macro must be a constant compile-time string (that is, text enclosed in quotation marks) that contains only ASCII characters. CFSTR returns a reference (textStringRef) to a CFString object. This will be used later. The call to the String Services function CFStringCreateWithPascalString converts a Pascal string (pascalString, of type Str255) to a CFString object. The reference to the CFString object is then passed in a call to the Window Manager function SetWindowTitleWithCFString to set the window's title. The call to the String Services function CFStringGetPascalString converts the CFString object (textStringRef) previously created by the CFSTR macro to a Pascal string (textString, of type Str255). 256, rather than 255, is passed in the bufferSize parameter to accommodate the length byte. textString is then passed in a call to the QuickDraw function DrawString, which draws the string in the window. The golden rules for releasing CFString objects are: if a "Create" or "Copy" function is used, CFString should be called to release the string when no longer required; if a "Get" function is used, CFString should not be called. Accordingly, CFRelease is called only in the case of titleStringRef. Note that CFRelease is not NULL-safe, so you must check for a non-NULL value before passing something to CFRelease.


Community Search:
MacTech Search:

Software Updates via MacUpdate

Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »
Snowboard Party 2 (Games)
Snowboard Party 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Crowned the best snowboarding game available on the market, Snowboard Party is back to fulfill all your adrenaline needs in... | Read more »
One Button Travel (Games)
One Button Travel 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: “To cut a long story short, If you like interactive fiction, just go buy this one.” - “Oozes the polish that... | Read more »
Light Apprentice Volume 1 (Games)
Light Apprentice Volume 1 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Light Apprentice Volume 1 includes Chapters 1 to 4, all gathered in a new exclusive game. When life in the world of... | Read more »
The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »

Price Scanner via

Black Friday deals on the Apple Watch and App...
Apple resellers are offering discounts and bundles with the purchase of an Apple Watch this Black Friday weekend. Below is a roundup of the deals being offered by authorized Watch resellers: Apple... Read more
Early Black Friday sale at B&H Photo, up...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1699 $300 off... Read more
NewerTech/OWC/MacSales Black Friday Deals 201... • Free Shipping available on nearly EVERYTHING on orders $35.00 & up within USA + • International Delivery Specials from $2.99+ Special Purolator... Read more
Walmart Black Friday deals: $100 off select i...
Walmart has released their Black Friday deals for 2015, now available online. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2: $399, $100 off MSRP - 16GB iPad Air: $... Read more
Photo Cleaner 1.0 Reclaims iPhone Storage Spa...
Seoul, Korea based mix1009 has announced the release and immediate availability of Photo Cleaner 1.0, their handy iPhone app that deletes the video portion of Live Photos, in order to reclaim space... Read more
Black Friday and Holiday sales on our price t...
Scan our Mac Price Trackers for the latest Black Friday and Holiday season information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the... Read more
Best Buy Black Friday deals: Up to $200 off M...
Best Buy has posted their Black Friday sale prices for 2015. Save on MacBook Pros, MacBooks, MacBook Airs, iMacs, iPads, and Apple Watches. Choose free shipping or free local store pickup (if... Read more
Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more
Target Black Friday Early Access deals: $100...
Target is offering early access to their Black Friday deals on Apple products on their online store for today, the 25th, only. Choose free shipping or free local store pickup (if available): - Apple... Read more

Jobs Board

Storefront Operations Coordinator, *Apple* -...
# Storefront Operations Coordinator, Apple -Latin America Job Number: 43587750 Miami, Florida, United States Posted: Oct. 16, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
*Apple* Enterprise / Government Professional...
# Apple Enterprise / Gove ment Professional Services Engineer Job Number: 42292976 Reston, Virginia, United States Posted: Aug. 18, 2015 Weekly Hours: 40.00 **Job Read more
iOS Wallet & *Apple* Pay Engineer - App...
# iOS Wallet & Apple Pay Engineer Job Number: 40586801 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** The iOS Read more
Software Engineer, *Apple* Watch - Clock Fa...
# Software Engineer, Apple Watch - Clock Face Team Job Number: 44368761 Santa Clara Valley, Califo ia, United States Posted: Nov. 14, 2015 Weekly Hours: 40.00 **Job Read more
Administrative Assistant, *Apple* Online St...
# Administrative Assistant, Apple Online Store Job Number: 43992352 Santa Clara Valley, Califo ia, United States Posted: Nov. 9, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.