Programming Guide

Opens a screen as a form

int sm_d_form(char *screen_address); 

int sm_l_form(int lib_desc, char *screen_name);

int sm_r_form(char *screen_name);

screen_address

A pointer to the screen's address in memory.

lib_desc

Specifies the library in which screen_name is stored, where lib_desc is an integer returned by sm_l_open. You must call sm_l_open before you read any screens from a library.

screen_name

The name of the screen.

• 0 Success.

• -1 Screen file's format is incorrect; previous form still displayed and available.

• -2 The screen cannot be found or the maximum allowable number of files is already open; previous form still displayed and available.

• -4 Unable to read the specified screen after the previous screen closed.

• -5 Insufficient memory available to display the screen.

sm_form and its variants open a screen as a form. Because these functions do not update the form stack, use them only with your own executive. To open a form while under Panther control, use a control string or sm_jform. To display a screen as a window, use sm_r_window, or one of its variants.

sm_form displays the named screen as a form. In so doing, it discards the previously displayed form and its window stack and frees their memory. The screen displays with its upper left-hand corner at the display's upper left position (0,0).

If the function returns an error code of -1 or -2, the previously displayed form remains on display and available for use. Other negative return codes indicate that the display is undefined. The caller should display another form before using screen manager functions.

If the form is stored in a library, you can use sm_l_form to display it. If the form is memory-resident, you can use sm_d_form. sm_r_form looks for the form in all possible areas, including the disk.

When you use sm_r_form, Panther looks for the named screen in the following locations in this order:

1. The application's memory-resident list; if found, sm_d_form is called to display the screen.
2. All open libraries; if found, sm_l_form is called to display the screen.

If the search fails and the supplied file name has no extension, Panther appends the SMFEXTENSION-specified extension to the file name and repeats the search. If all searches fail, sm_r_form displays an error message and returns.

You can save processing time by using sm_d_form to display memory-resident screens. Memory-resident screens are useful in applications with a limited number of screens, and in environments with a slow disk. A memory-resident screen never changes at runtime, so it can be made sharable on systems that support sharing read-only data. sm_r_form can also display memory-resident screens if they are properly installed with sm_formlist. To create memory-resident screens, use bin2c to convert editable screens from disk files to program data structures that you can compile into your application.

You can also save processing time with sm_l_form to display screens from a library. A library is a single file that stores screens, JPL modules, and menus. You can assemble a library from individual screen files with formlib. Libraries let you distribute a large number of screens with an application, and can improve efficiency by reducing the number of search paths.

#include <smdefs.h>
	#include <setjmp.h>

	/* If an abort condition exists, read in a special
	 * form to handle that condition, discarding all
	 * open windows. */

	extern jmp_buf re_init;

	if (sm_isabort(ABT_OFF) > 0)
	{
	   sm_r_form("badstuff");
	   if (sm_message_box("Do you want to continue?", 0,
	       SM_MB_YESNO, 0) == SM_IDYES)
	      longjmp(re_init);
	   else sm_cancel();
	}

sm_r_window, sm_r_at_cur, sm_formlist

---

---