JAM C Programmer's Guide

 

                                    Contents

 

 

 

1  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1  The JAM Run-time Environment  . . . . . . . . . . . . . . . . . . . . . . 1

1.2  Functions Invoked by Control Links  . . . . . . . . . . . . . . . . . . . 1

1.2.1  Return Values and Target Lists  . . . . . . . . . . . . . . . . . . . . 1

1.2.2  Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3  Functions Attached to Fields  . . . . . . . . . . . . . . . . . . . . . . 3

1.3.1  Invocation  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.3.2  Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.3.3  Return Value  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3.4  Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.4  Screen Entry and Exit Functions . . . . . . . . . . . . . . . . . . . . . 5

1.4.1  Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4.2  Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.5  The Function Lists  . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.6  The JAM Main Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.7  Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

 

 

2  Overview of Library Functions . . . . . . . . . . . . . . . . . . . . . . . 9

2.1  Variants  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.2  Initialization  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

2.3  Form Display  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

2.4  Data Entry  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

2.5  Keyboard Entry  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

2.6  Cursor Control  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12

2.7  Data Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  12

2.8  Mass Storage and Retrieval  . . . . . . . . . . . . . . . . . . . . . .  13

2.9  Message Display . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

2.10  Altering the Operation of Other Functions  . . . . . . . . . . . . . .  14

2.11  Scrolling and Shifting Functions . . . . . . . . . . . . . . . . . . .  14

2.12  Validation Routines  . . . . . . . . . . . . . . . . . . . . . . . . .  15

2.13  Miscellaneous  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

2.14  Which Function Do I Use? . . . . . . . . . . . . . . . . . . . . . . .  15

 

 

3  Library Functions by Name . . . . . . . . . . . . . . . . . . . . . . . .  16

 

 

4  Built-in Invoked Functions  . . . . . . . . . . . . . . . . . . . . . . . 236

 

 

5  Environment and Configuration Files . . . . . . . . . . . . . . . . . . . 244

 

 

6  Keyboard Input  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

6.1  Logical Characters or Keys  . . . . . . . . . . . . . . . . . . . . . . 245

6.2  Key Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

6.3  Key Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

 

 

7  Screen Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

7.1  Graphics Characters and Alternate Character Sets  . . . . . . . . . . . 247

7.2  The Status Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

 

 

8  User-definable Functions  . . . . . . . . . . . . . . . . . . . . . . . . 249

8.1  Installation  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

8.2  Memo Text Edits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

9  The Local Data Block  . . . . . . . . . . . . . . . . . . . . . . . . . . 251

 

 

10  Writing Portable Applications  . . . . . . . . . . . . . . . . . . . . . 252

10.1  Terminal Dependencies  . . . . . . . . . . . . . . . . . . . . . . . . 252

10.2  Items in smmach.h  . . . . . . . . . . . . . . . . . . . . . . . . . . 252

 

 

11  Writing International Applications . . . . . . . . . . . . . . . . . . . 253

11.1  Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

11.2  Characters Outside the U.S. ASCII Set  . . . . . . . . . . . . . . . . 253

 

 

12  Writing Efficient Applications . . . . . . . . . . . . . . . . . . . . . 253

12.1  Memory-resident Screens  . . . . . . . . . . . . . . . . . . . . . . . 253

12.2  Memory-resident Configuration Files  . . . . . . . . . . . . . . . . . 254

12.3  Message File Options . . . . . . . . . . . . . . . . . . . . . . . . . 255

12.4  Avoiding Unnecessary Screen Output . . . . . . . . . . . . . . . . . . 255

12.5  Stub Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

 

 


 

1 Introduction

 

The Programmer's Guide explains how to write code that works with the JAM

run-time environment. First, we offer a general explanation of how to build your

routines into the run-time system. Then, the library itself is classified into

categories, and an alphabetical listing of all the functions with full

explanations appears. Finally, there are explanations of internal processing and

tips for writing better applications; this material is organized topically, and

is better browsed or used for reference than read straight through.

 

 

1.1  The JAM Run-time Environment

 

A salient fact of programming with JAM is that the application program has no

main control loop. Control flow is handled by JAM's main routine, which uses

control strings to decide how to respond to what you type; your own code is made

up chiefly of screen entry and exit functions, invoked functions, and attached

functions. Invoked functions are placed in JAM control strings; they are called

immediately upon receipt of a user's menu pick or function key, and may prompt

for parameters with an argument window. Attached functions, on the other hand,

are associated with data entry fields, and are called with a predefined set of

arguments when the cursor enters or leaves a field. The next several sections

describe each type of function and provide examples.

 

It is, of course, possible to gain full control of screen and keyboard

processing, by using the library routines. Section 2 categorizes those routines

and describes their typical use. It is further possible to alter or abolish the

processing of control links by writing your own main routine.

 

1.2  Functions Invoked by Control Links

 

A function whose name appears in a JAM control string, preceded by a caret ^,

will be called when a user selects the function key or menu pick associated with

that control string. This means that JAM must be linked with the function. See

Section 1.5 for a detailed explanation of how to link functions with JAM. JAM

supplies a number of built-in invoked functions, which are documented in Section

4 of this chapter.

 

Invoked functions are passed a single argument, a pointer to a character string.

In the simplest case the string is just the contents of the control field (the

function name plus any following text), with the leading caret stripped off.

However, if the control field contains one or more argument window

specifications (a percent character % followed by the name of a window), the

function receives their contents: JAM opens each window for data entry, then

substitutes the concatenated contents of its fields for the percent

specification, before calling the function. See the Author's Guide for details

on how to create argument windows.

 

1.2.1  Return Values and Target Lists

 

The integer return value from an invoked function is ignored, unless

 

  1.  it is the value of a logical key with an associated control string on

      the current screen (EXIT, XMIT, PF1, etc.), or

  2.  the control string contains a target list.

 

If there is no target list and the return value is a logical key with an

associated control string, JAM will execute the control string. Invoked

functions can be chained in this fashion; programmers are responsible for

avoiding looping chains.

 

A target list in a control string provides for more flexible and

better-documented chaining of invoked functions. Syntactically, a target list


 

appears between the caret and the function name, and must be enclosed in

parentheses. It consists of one or more pairs, of the form

 

     return-value = control-string

 

Here return-value is an integer code returned from the invoked function,

expressed as a decimal or hexadecimal integer, a quoted ASCII character, or a

logical key mnemonic (refer to smkeys.h  for a list). Control-string is any JAM

control string, which will be executed whenever the function returns

return-value. If the target list contains more than one such pair, as is likely,

separate them with semicolons.

 

In the control string below, a return value of -1 from the function process

causes the function cleanup to be invoked, while a return value of 0 causes a

window named step2 to be displayed:

 

     ^(-1=^cleanup; 0 = &(8,25)step2)process step1

 

Target lists may nest; that is, caret control strings in a target list may

themselves contain target lists.

 

1.2.2  Example

 

The example below shows a function invoked when a user hits TRANSMIT or EXIT on

its screen; it simply saves the contents of the screen in a flat data file. The

two control strings that call it would look like this:

 

     XMIT =>    ^save

     EXIT =>    ^(0=^jm_exit)save close

 

And here is the function itself:

 

#include "smdefs.h"

#Include "smidty.h"

#include "myrec.h"

 

/* The following is an invoked function bound to the

 * TRANSMIT key. It saves the contents of the screen

 * in the data structure 'myrec' and writes it to a file,

 * which is opened if necessary. The argument determines

 * whether the file should be closed; it is in the control

 * string.

 * The data structure myrec is assumed to be defined in

 * "myrec.h", generated from the screen by the f2struct

 * utility.

 */

 

int save (closeflag)

char *closeflag;

{

     struct myrec myrec;

     int count;

     static FILE *savefile;

 

     if (strcmp (closeflag, "close") == 0)

     {

          if (savefile != 0)

               fclose (savefile);

          return 0;

     }

 

     sm_wrtstruct ((char *)&myrec, &count, 0);

 

     if (savefile == 0)

     {

          savefile = fopen ("savefile", F_B_WRONLY);

          if (savefile == 0)

               return -1;

     }

     if (fwrite ((char *)&myrec, 1, count, savefile) != count)

          return -1;

 

     return 0;

}

 

/* Code to install the invoked function above */

struct fnc_data invlist[] = {

     { "save", save, 0, 0, 0, 0 }

};

int howmanyinv = sizeof(invlist) / sizeof(struct fnc_data);

 

sm_install (CARET_FUNC, invlist, &howmanyinv);

 

 

1.3  Functions Attached to Fields

 

Field entry and field exit functions are both called attached functions, because

they are associated with a specific data-entry field. You attach a function to a

field by placing its name in the field entry or validation function slot of the

screen editor's pop-up windows. (You may place the same function in both slots,

and use the fourth parameter to determine the context of the call; see below.)

 

To attach a JPL procedure to a field, you can type your code directly into the

screen editor's JPL procedure window. If the JPL procedure is long or useful in

many places, you can also put it in a file, and enter jpl filename in the

attached function window. You may attach JPL code to both hooks, in which case

the attached function is executed before the embedded procedure.

 

1.3.1  Invocation

 

A field exit function, also commonly called a validation function, is called:

 

  1.  As part of field validation, when you exit the field by filling it or

      by hitting the TAB or RETURN key; BACKTAB and arrow keys do not

      normally cause validation. These circumstances are subject to

      modification by sm_ok_options, q.v.

  2.  As part of screen validation (sm_s_val), when the TRANSMIT key is hit.

  3.  When application code calls sm_fval directly.

 

A field entry function is called from sm_openkeybd whenever the cursor enters

its field.

 

1.3.2  Arguments

 

All attached functions receive four arguments:

 

  1.  the field number

  2.  a pointer to the buffer containing a copy of the field's contents

  3.  the data's occurrence number

  4.  an integer containing the VALIDED and MDT bits associated with the item

      or field, plus more flag bits indicating why the function was called;

      refer to the following table.

 

   Bit name    Meaning

   VALIDED     If set, indicates that the field has passed all its

               validations, and has not been modified since.

   MDT         If set, indicates that the field has been modified, either by

               keyboard input or a library function such as sm_putfield,

               since the current screen was first displayed. It is never

               cleared by JAM, but you may clear it using sm_bitop.

   K_ENTEXIT   If set, indicates that the function has been called upon field

               entry. This bit enables a single function to be used for both

               field entry and exit.

   K_KEYS      This is a mask for the remaining values in this table. You

               should and the function's fourth parameter with this value,

               then test for equality to one of the five below, thus:

 

               if ((parm4 & K_KEYS) == K_SVAL)

   K_NORMAL    A normal data key caused the cursor to enter or exit the field

               in question.

   K_BACKTAB   The BACKTAB key caused the cursor to enter or exit the field

               in question.

   K_ARROW     An arrow key caused the cursor to enter or exit the field in

               question.

   K_SVAL      The field is being validated as part of screen validation

               (TRANSMIT key or sm_s_val).

   K_USER      The application has invoked the function directly, as through

               sm_fval.

   K_OTHER     Another key, such as HOME, caused the cursor to enter or exit

               the field in question.

 

 

A field exit function is called whether or not the field was previously

validated; it may test the VALIDED and MDT flags to avoid redundant processing.

It is called only after the field's contents pass all other validations.

 

1.3.3  Return Value

 

If no error occurs, the function should return 0. At this point, the screen

manager's validation routine will set the VALIDED bit, if it was not already

set. Any nonzero value returned by the function is interpreted as an error. If

the returned value is 1, the cursor is not repositioned; if it is any other

nonzero value, the cursor is repositioned to the field undergoing validation. In

either case, the VALIDED bit is unchanged.

 

1.3.4  Example

 

Here is code for an attached function that does nothing much:


 

#include "smdefs.h"

 

int apfunc1 (field_number, field_data, occurrence, val_mdt)

int field_number, occurrence, val_mdt;

char *field_data;

{

     int error;

     extern int lookup();

     char errbuf[128];

 

     /* If field is unchanged since last validation, skip */

     if (val_mdt & VALIDED)

          return (0);

 

/* Check field for validity (externally defined) */

     error = lookup (field_data);

 

     if (error)

     {

          /* Notify user of error condition. */

          sm_gofield (1);

          sprintf (errbuf, "Can't find %s; please re-enter all data.",

               field_data);

          sm_quiet_err (errbuf);

          return (1);

                    /* leave cursor in field 1 */

     }

     else return (0);

}

 

 

While an attached function is free to display windows, it must not display a

form. To do so would wipe out the form or window to which the function was

attached. For the same reason, attached functions must take care to close all

the windows they may open before returning to sm_openkeybd.

 

1.4  Screen Entry and Exit Functions

 

Screens, like fields, may have entry and exit functions defined in the screen

editor. The screen entry function is called after the screen has been displayed,

but before control returns from sm_r_window, sm_d_form, or whatever you use to

display the screen. There are several steps in screen initialization, performed

in the following order:

 

  1.  The new screen is displayed, as a form or window.

  2.  The screen-entry function is called.

  3.  The jam_first control string is executed. (This is an obsolescent

      feature.)

  4.  Screen fields are updated with values from the local data block (LDB

      merge).

  5.  The jam_auto control string is executed.

 

During screen initialization, entering data into fields with sm_putfield or

other library routines will not cause the fields' MDT bits to be set; this

applies to the LDB merge as well. If you want to set MDT bits, call sm_bitop.

 

Screen exit functions are called after named items have been stored in the LDB,

but before the screen is removed from the display and its data structures

destroyed. They are called from sm_close_window, and also from sm_r_form and the

other form-display functions, which cause all open windows to be destroyed

automatically. This implies that the screen may not always be visible when your

exit function is called.


 

1.4.1  Arguments

 

Screen entry and exit functions receive two parameters:

 

  1.  The name of the screen, if available. It will not be available if the

      screen is memory-resident and displayed using sm_d_window or a variant.

  2.  A flag containing the following bits, defined in smdefs.h :

         K_ENTEXIT   Set if the function was called during screen entry,

                     clear during exit.

         K_NORMAL    Set if the function was called from sm_close_window,

                     clear otherwise.

 

A single function used for both entry and exit can use this bit to distinguish

its context. One advantage of coding screen entry and exit processing in the

same function is that persistent variables, such as pointers to dynamically

allocated buffers, can be made static rather than global.

 

Any value returned from a screen entry or exit function is ignored.

 

1.4.2  Example

 

Here is an example of a screen entry function. This one loads up an item

selection list from a disk file whose name is stored in the screen.

 

#include "smdefs.h"

 

/* Here is a screen entry function for a generic item

 * selection screen. It turns the screen name into the

 * name of a text file containing a list of items, one

 * per line, and loads them into the array named "items".

 * This technique could be easily adapted to query a database

 * instead.

 */

 

void gen_entry (name, context)

char *name;

int context;

{

     FILE *inf;

     char line[256];

     int k;

 

     sprintf (line, "%s.dat", name ? name : "default");

     if ((inf = fopen (line, "r")) == 0)

          return;

     for (k = 1; fgets (line, sizeof(line), inf); ++k)

          sm_i_putfield ("items", k, line);

     fclose (inf);

}

 

/* Here is code to install the above function in the screen

 * entry function list. */

static struct fnc_data sentry[] = {

     { "gen_entry", gen_entry, 0, 0, 0, 0 }

};

int count;

 

count = sizeof(sentry) / sizeof(struct fnc_data);

sm_install (FENTRY_FUNC, sentry, &count);


 

1.5  The Function Lists

 

JAM stores function names as text strings in screen files. It needs to associate

these names with the functions' addresses in order to call them. You must

furnish this association by building lists of data structures called function

lists. Attached, invoked, and screen entry functions must all appear; there is

one list for each type of function. For example, if an application's screens

contained two functions named apfunc1 and apfunc2 that were attached to a field,

and another named invoca in a caret control string, its startup code would need

to include the following:

 

#include "smdefs.h"

#define C_FUNCTION 0

 

extern int apfunc1(), apfunc2();

 

struct fnc_data funlist[] =

{

     { "apfunc1", apfunc1, C_FUNCTION, 0, 0, 0 },

     { "apfunc2", apfunc2, C_FUNCTION, 0, 0, 0 },

};

/* The following definition saves a lot of grief */

int howmuchfun = sizeof(funlist) / sizeof(struct fnc_data);

 

extern int invoca();

 

struct fnc_data invlist[] =

{

     { "invoca", invoca, C_FUNCTION, 0, 0, 0 }

};

int howmanyinv = sizeof(invlist) / sizeof(struct fnc_data);

 

...

sm_install (ATTCH_FUNC, funlist, &howmuchfun);

sm_install (CARET_FUNC, invlist, &howmanyinv);

...

 

 

In the structure definitions, the quoted strings are names as entered on the

screen, and the non-quoted entries are addresses of functions. Note that the two

need not always be the same; in particular, the same function can be entered in

the list under different names, or aliases. Possible uses for this technique

include mapping functions yet to be written to a stub routine, and using the

same function to perform slightly different tasks (with the name as an implied

parameter).

 

Refer to the library page on sm_install, and to preceding sections, for fuller

details about each type of function.

 

 

1.6  The JAM Main Programs

 

As a starting point for your own applications, JYACC provides source code for a

main routine, in a file named jmain.c. This routine performs various necessary

initializations before calling JAM's main control loop, which resides in a

library. You can modify the main routine to change the default settings and,

more importantly, to install your application code with calls to sm_install, as

in the previous section. Extensive documentation in the source code will show

you where and how to make your modifications.

 

You will find similar source files, fmain.c and jxmain.c, that are main routines

for the authoring programs, xform and jxform. Under Release 4.0, you may link

your application code into the authoring environment as well as the run-time


 

system. This enables you to prototype and revise your screens with even greater

convenience than before.

 

 

Refer to the Installation Notes for your system for the locations of these

files. For additional hints on putting your application together, take a look at

the sample programs (next section).

 

1.7  Sample Programs

 

JYACC supplies a number of sample programs and screens to demonstrate the use of

JAM routines and the procedures you must use to compile and link application

programs. They include both programs that supply their own main routine, and

programs that use the one provided with JAM. They can generally be found in a

subdirectory, named samples, of the directory where JAM has been installed.

Refer to the Installation Notes for your specific system for a list of the files

making up the sample programs.


 

2 Overview of Library Functions

 

After screens have been created with the JAM authoring utility, an application

program can access them using routines from the library. A typical sequence

follows.

 

     Note that the JAM environment performs something very similar to this

     sequence, and it is not generally necessary for application programs

     to do it; application code is simply attached to fields and function

     keys. Only in circumstances where very tight control over data entry

     is required should it be necessary for an application program to do

     all this work.

 

  1.  sm_initcrt is called to initialize the terminal.

  2.  sm_r_form is called to bring up a form on the screen.

  3.  The application program may call sm_putfield, or a variant, to

      initialize fields. This can be done as often as desired, and at any

      time.

  4.  sm_openkeybd is called, and you may key data into unprotected fields.

  5.  One or more data access routines are called to return the fields'

      current contents to the application program.

  6.  While the data contain errors or inconsistencies:

 

        a.  sm_gofield, or a variant, is called to reposition the cursor

            to the field containing the error.

        b.  sm_err_reset is called to display an error message.

        c.  sm_openkeybd is called to accept fresh data.

 

  7.  If special conditions require additional input:

 

        a.  sm_r_window, or a variant, is called to bring up a window with

            additional fields. The entire sequence may be repeated here

            recursively.

        b.  sm_close_window is called to close the current window and

            restore the immediately previous display.

 

  8.  sm_resetcrt is called to reset the terminal prior to exiting.

 

2.1  Variants

 

Many library routines deal with fields. Most of these have several variants that

accept different sorts of field designations, enabling the application

programmer to choose the most convenient. The variants are, by convention,

distinguished by prefixes to the function name:

 

   Prefix         Field designation

   sm_            Field number only

   sm_o_          Field number and occurrence number

   sm_n_          Field name only

   sm_i_          Field name and occurrence number

   sm_e_          Field name and onscreen element number

 

In the library section of the manual, only the first variant is documented. The

behavior of the others is identical, save for the handling of errant field

specifications. Also, the n_ and i_ variants will operate on fields that do not

appear in the current screen but are in the local data block.

 

A similar convention exists for library routines that display screens, depending

on whether the screens file is on disk, in memory, or included in a screen

library. The prefixes are as in the table below. All these functions are

documented separately.

 

   Prefix         Screen file storage

   sm_r_          Single disk-resident file

   sm_d_          Memory-resident file

   sm_l_          Member of screen library

 

Most JAM library routines fall into one of the following categories:

 

   .

      Initialization

   .

      Form display

   .

      Data entry (from the application program)

   .

      Keyboard entry

   .

      Cursor control

   .

      Data access (by the application program)

   .

      Mass storage and retrieval

   .

      Message display

   .

      Altering the operation of other library routines

   .

      Scrolling and shifting

   .

      Data validation

 

The following sections summmarize the routines within each category. Modules

calling JAM library routines should include smdefs.h . Modules testing for

non-ASCII values returned by sm_getkey, sm_openkeybd or sm_menu_proc should also

copy or include smkeys.h .

 

2.2  Initialization

 

The following routines are called for initialization.  Note that, by default,

most of these are called to set up the JAM run-time environment, and the

application program need not call them itself.

 

   sm_initcrt       Initializes the terminal for JAM, and saves the path name

                    for disk resident forms and windows.

   sm_keyinit       Initialize memory-resident key translation file.

   sm_msgread       Loads message files.

   sm_vinit         Initialize memory-resident video file.

   sm_smsetup       Initialize memory-resident configuration variable file.

                    sm_unsetup restores the default configuration.

   sm_formlist      Add to the list of memory-resident forms.

   sm_rmformlist    Destroys the memory-resident form list.

   sm_install       Installs attached functions, screen entry/exit functions,

                    and other user routines to be called from library

                    functions.

   sm_resetcrt      Restores normal terminal characteristics before exiting.

   sm_leave         Prepares the display for a temporary escape from JAM to

                    the operating system.

   sm_return        Prepares the display to resume processing after an

                    sm_leave.

   sm_cancel        Resets the terminal and exits. Normally bound to a

                    keyboard interrupt handler.

   sm_fextension    Changes the default file extension for screen files.

   sm_inictrl       Changes the default control string bindings for function

                    keys.


 

2.3  Form Display

 

The following routines are called to display screens.

 

   sm_r_form        Displays a form. Any previously displayed form is

                    cleared. Similarly, sm_d_form, sm_l_form.

   sm_r_window      Displays a window at a specified line and column on the

                    screen. The previous contents of the window area are

                    saved. Similarly, sm_d_window, sm_l_window.

   sm_r_at_cur      Displays a window at the current cursor position. The

                    previous contents of the window area are saved.

                    Similarly, sm_d_at_cur, sm_l_at_cur.

   sm_close_window  Closes the current window and restores the immediately

                    previous display.

   sm_wselect       Brings a "buried" window to the active position.

                    sm_wdeselect puts it back.

   sm_l_open        Opens a form library.

   sm_l_close       Closes a form library.

   sm_hlp_by_name   Displays the help screen attached to the current field or

                    screen, gets user input, and restores the previous

                    display.

   sm_rescreen      Refreshes the screen display.

 

2.4  Data Entry

 

The following routines enable an application program to enter data into fields

in a screen or the local data block, or to change its display attributes.

 

   sm_putfield      Copies the data from a string into a specified field or

                    occurrence. If the string is too long for the field, it

                    is truncated.

   sm_amt_format    Copies a string into the specified amount field or

                    occurrence, after applying the currency format.

   sm_itofield      Converts an integer to a string, and copies the string

                    into the specified field or occurrence.

   sm_dtofield      Converts a double floating point value to a string,

                    applies a field currency edit if it exists, and copies

                    the string into the specified field or occurrence.

   sm_ltofield      Converts a long integer to a string and copies the string

                    into the specified field or occurrence.

   sm_calc          Evaluates a mathematical expression, possibly involving

                    field values, and places the result in a field.

   sm_ldb_init      Initialize the local data block from the data dictionary.

   sm_lclear        Clear all occurrences with a given scope in the LDB.

   sm_lreset        Reinitialize all occurrences in the LDB with a given

                    scope.

   sm_chg_attr      Changes the display attributes of a field.

   sm_achg          Changes the display attributes of a scrolling data item.

   sm_cl_unprot     Clears onscreen and offscreen data from unprotected

                    fields on the current screen. Date and time fields that

                    take system values are reset.

   sm_cl_everyfield Clears all field data, onscreen and off, regardless of

                    field protection.

   sm_1clear_array  Clears all data from a scrolling array.

   sm_clear_array   Clears all data from a scrolling array and all parallel

                    scrolling arrays.

   sm_ioccur        Inserts a blank occurrence into an array or scroll.

   sm_doccur        Deletes an occurrence from an array or scroll.

 

2.5  Keyboard Entry

 

The following routines accept and process data entered from the  keyboard.


 

   sm_getkey        Returns the interpreted value of the key hit. In the case

                    of a displayable key, this is its standard ASCII value;

                    in the case of a function key with special meaning to

                    JAM, this is a value defined in the file smkeys.h . This

                    function is used by all other keyboard input functions.

   sm_ungetkey      Pushes a key back on the input stream, to be retrieved by

                    sm_getkey.

   sm_openkeybd     Accepts and interprets user keyboard entry. Displayable

                    data is entered into fields on the screen, subject to any

                    restrictions or edits that were defined for those fields

                    (see the JAM Author's Guide). Function keys control the

                    position of the cursor and aid in editing data.

   sm_menu_proc     Returns the initial character of the user's selection

                    from a menu whose entries start with distinct ASCII

                    characters.

   sm_choice        Returns the text of the chosen entry on a menu screen.

   sm_query_msg     Displays a question on the status line, and returns a yes

                    or no answer.

   sm_keyhit        Tests whether a key has been hit during a specified

                    interval.

   sm_isabort       Returns control to the application through nested

                    keyboard entry routines.

 

2.6  Cursor Control

 

The following routines affect the positioning and visibility of the cursor.

 

   sm_getcurno      Returns the number of the field within which the cursor

                    is currently positioned.

   sm_home          Places the cursor in the first unprotected field.

   sm_last          Positions the cursor to the start of the last unprotected

                    field of the current form.

   sm_tab           Moves the cursor to the next unprotected field, or to the

                    unprotected field specified by a next field edit.

   sm_nl            Moves the cursor to the next unprotected field following

                    the current line on the screen.

   sm_backtab       Moves the cursor to the start of the current field, or if

                    it is already there, to the start of the previous

                    unprotected field.

   sm_gofield       Positions the cursor to the start of the specified field

                    or occurrence.

   sm_off_gofield   Positions the cursor to a given offset from the start of

                    the specified field.

   sm_disp_off      Returns the displacement of the cursor from the starting

                    column of the current field.

   sm_c_off         Turns the cursor off.

   sm_c_on          Turns the cursor on.

   sm_c_vis         Turns the cursor position display at the end of the

                    status line on or off.

 

2.7  Data Access

 

The following routines give an application program access to data entered on a

screen or in the LDB.

 

   sm_edit_ptr      Returns the text of a special field edit.

   sm_getfield      Returns the contents of a field or occurrence in a buffer

                    supplied by the user.

   sm_fptr          Returns the contents of a field in an internal buffer.

   sm_pkptr         Returns the contents of a field in an internal buffer,

                    with as many blanks as possible removed.

   sm_strip_amt_ptr Returns the contents of a field, stripped of any

                    extraneous characters supplied by currency formatting.


 

   sm_num_occurs    Returns the largest number of items entered so far into a

                    scrollable field or array.

   sm_intval        Returns the integer value of the data found in the

                    specified field or occurrence.

   sm_dblval        Returns the double floating point value of the data found

                    in the specified field or occurrence.

   sm_lngval        Returns the long integer value of the data found in the

                    specified field or occurrence.

   sm_is_yes        Returns 1 if the first character of a yes/no field looks

                    like yes, and 0 otherwise.

   sm_dlength       Returns the length of the data currently in the specified

                    field or occurrence.

   sm_allget        Merge LDB data items onto the screen.

   sm_lstore        Store screen data into the LDB.

 

2.8  Mass Storage and Retrieval

 

The following functions move data to or from groups of fields in the screen or

LDB.

 

   sm_save_data     Writes the contents of the current form's fields to a

                    buffer for subsequent retrieval.

   sm_restore_data  Restores all fields to the current form from a buffer

                    created by sm_save_data.

   sm_sv_data       Writes the contents of some of the current form's fields

                    to a buffer for subsequent retrieval.

   sm_rs_data       Restores part of the current form from a buffer created

                    by sm_sv_data.

   sm_wrtstruct     Copies the current form's fields to a program data

                    structure generated from the screen.

   sm_rdstruct      Reads into the current form's fields from such a data

                    structure.

   sm_wrt_part      Writes the contents of some of the current form's fields

                    to such a data structure.

   sm_rd_part       Reads some of the current form's fields from such a data

                    structure.

   sm_rrecord       Copies from a data structure defined by a data dictionary

                    record to the screen or LDB.

   sm_wrecord       Copies from the screen to such a data structure.

 

2.9  Message Display

 

The following routines display a message on the status line of the screen

(typically the bottom line).

 

   sm_d_msg_line    Displays a message with a user-supplied display

                    attribute.

   sm_msg           Displays a message at a given column on the status line.

   sm_err_reset     Displays a message using a standard error message

                    attribute. Processing is halted until the user hits the

                    space bar, at which time the status line is reset.

                    Similarly, sm_emsg.

   sm_quiet_err     Displays the word ERROR: followed by the user-supplied

                    message. Processing is halted until the user hits the

                    space bar, at which time the status line is reset.

                    Similarly, sm_qui_msg.

   sm_mwindow       Displays your message in a pop-up window, at a location

                    you specify.

   sm_query_msg     Displays a user-supplied question. Processing is halted

                    until the user answers yes or no, at which time the

                    status line is reset, and the answer is returned to the

                    calling program.

   sm_msg_get       Gets a message from the message file. So does sm_msgfind.


 

   sm_setbkstat     Displays a background message, which will be hidden if

                    the cursor enters a field that has status text, or if

                    another message display routine is called.

   sm_setstatus     Turns on or off the automatic display of alternating

                    Ready and Wait status line messages, corresponding to an

                    open or closed keyboard.

 

2.10  Altering the Operation of Other Functions

 

These functions affect the behavior of other parts of the run=-time system. Many

have corresponding setup variables, so that you can experiment with different

conditions with no need to change or recompile your application; see the

Configuration Guide's section on setup.

 

   sm_er_options    Changes the way sm_err_reset and related functions handle

                    error message acknowledgement.

   sm_ch_form_atts  Changes the display attributes of standard windows used

                    by the run-time system.

   sm_ch_emsgatt    Changes the display attributes used by sm_err_reset and

                    sm_quiet_err.

   sm_ch_qmsgatt    Changes the display attribute used by sm_query_msg.

   sm_ch_stextatt   Changes the display attribute used for the status line

                    text associated with fields.

   sm_ch_umsgatt    Changes the display attributes used for error windows.

   sm_mp_options    Sets options for sm_menu_proc.

   sm_mp_string     Changes sm_menu_proc's interpretation of data keys.

   sm_ok_options    Changes the way sm_openkeybd interprets arrow keys, field

                    validation, and other items.

   sm_zm_options    Changes details of the way zooming is done.

   sm_dicname       Changes the application's data dictionary name.

   sm_dd_able       Turns LDB write-through on or off.

 

   sm_keyfilter     Turns the keystroke playback/recording mechanism on or

                    off.

   sm_dw_options    Turns JAM delayed write on or off.

 

2.11  Scrolling and Shifting Functions

 

The following routines refer specifically to scrollable or shiftable fields.

Some are listed above, and repeated here for convenience. The sm_e_ prefix is

not used for scrolling routines, since the element numbers of an array designate

the individual on-screen fields which constitute that array, and the scrolling

routines normally process an array as a whole. Individual items within a

scrolling field or scrolling array are referred to by item number, which is

independent of which items are currently displayed on the screen.

 

   sm_t_scroll      Determines whether the specified field or array is

                    scrollable.

   sm_item_id       Returns the item number of the data in the current

                    scrollable field.

   sm_sc_max        Changes the maximum number of items in a scrollable field

                    or array.

   sm_clear_array   Clears all data from a scrollable array and all parallel

                    scrollable arrays.

   sm_rscroll       Scrolls a single scrollable field or array, or a group of

                    parallel scrollable fields or arrays, by a given amount.

   sm_ascroll       Scrolls a single scrollable field or array, or a group of

                    parallel scrollable fields or arrays, to a given

                    location.

   sm_num_items     Returns the largest number of items entered so far into a

                    scrollable field or array.

   sm_t_shift       Determines whether the specified field or array is

                    shiftable.


 

   sm_oshift        Shifts the contents of the current shiftable field or

                    array.

   sm_sh_off        Returns the displacement of the cursor from the start of

                    the shiftable data in the current field.

   sm_ind_set       Turns shifting and scrolling field indicators on or off.

 

2.12  Validation Routines

 

   sm_fval          Forces field validation and end of field processing.

   sm_s_val         Performs field validation and end of field processing on

                    all fields of the current form.

   sm_bitop         Tests, sets, and clears a number of bits associated with

                    field validation. Overlaps with some more specialized

                    routines listed below.

   sm_novalbit      Resets the validated bit of a field, so that the field

                    will (again) be subject to validation when it is next

                    filled or tabbed from.

   sm_cl_all_mdts   Resets the modified bits of all occurrences of every

                    field.

   sm_tst_all_mdts  Returns the field and occurrence numbers of the first

                    occurrence that has its modified bit set.

 

2.13  Miscellaneous

 

   sm_occur_no      Returns the occurrence number of the data in the field

                    where the cursor is.

   sm_max_occur     Returns the number of the maximum occurrence that can be

                    entered in the specified field or array.

   sm_n_fldno       Returns the number of a field, given its name.

   sm_base_fldno    Returns the field number of the base element of an array,

                    obtained from the field number of any element of the

                    array.

   sm_size_of_array Returns the number of elements in an array.

   sm_length        Returns the length of a field (not its contents).

   sm_1protect      Protects a field from some combination of tabbing into,

                    data entry, validation, and clearing. sm_protect does all

                    four.

   sm_1unprotect    The inverse of sm_1protect.

   sm_aprotect      Sets protection on an entire array. sm_aunprotect

                    reverses the effect.

   sm_sdate         Returns current system date information in a formatted

                    string.

   sm_stime         Returns current system time information in a formatted

                    string.

   sm_do_region     Paints arbitrary data on one line of the display.

   sm_hlp_by_name   Invokes a named help window on the current field.

   sm_flush         Forces buffered updates out to the display; JAM buffers

                    them for greater efficiency. sm_m_flush just flushes the

                    message line.

   sm_resize        Changes the size of the display area available to JAM.

   sm_bel           Beeps or flashes the terminal.

   sm_keylabel      Given a logical key name, returns its label on a real

                    keyboard.

   sm_label_key     Initialize a softkey label.

   sm_plcall        Invoke a routine written in the JYACC Procedural

                    Language.

   sm_putjctrl      Replace a JAM control string for a function key.

   sm_rescreen      Redraw the display if it gets garbled.

 

2.14  Which Function Do I Use?

 

The JAM library provides more than one way of doing certain things. Following

are some guidelines for choosing the right ones.


 

Screen storage and display. There are three ways to store screens for display:

in individual disk files, in memory, and in a form library. This involves the

sm_r_, sm_d_, and sm_l_ families of functions respectively. The first method is

the most flexible, since the screen editor operates only on disk files; it is

clearly best in the early development stages of an application. Form libraries

are useful to reduce the clutter of a large number of screen files, and also to

reduce the overhead of file system access, once an application is in production.

Memory-resident forms are still faster to bring up, although they consume extra

memory.

 

The most flexible way is to combine all three, using the memory-resident form

list and SMFLIBS setup variable. The sm_r_ family of functions can be used to

display disk-, library-, or memory-resident screens; if a screen needs

alteration, you can simply remove it from the list or library and the altered

disk copy will be used. The JAM run-time system uses the sm_r_ family, so all

three options are open to you.

 

Field names and numbers. It is normally best to refer to fields by name rather

than by number. The reason is that any addition, deletion, or shuffling of

fields on the screen alters their numbering, with unpredictable consequences for

programs that use hard-coded field numbers.

 

There are nevertheless certain situations where it makes sense to use field

numbers. A common one is where a group of fields bear some relation to one

another, so that their ordering will not change; in this case, the number of the

first field can be obtained from its name and the rest processed in a loop on

the field number. Such a loop is much more convenient than processing a group of

fields by name. Attached functions are another example; they are passed the

field number as a parameter, and it makes sense to use it for direct access to

that field, or to offset it for access to related fields.

 

A further consideration for JAM applications is that unnamed fields cannot

appear in the LDB or data dictionary.

 

Data retrieval. There are three sets of routines for retrieving data from a

field: sm_fptr, sm_pkptr, and sm_getfield. The first two share a limitation:

they store their results in a small ring of buffers which are overwritten after

a few subsequent calls to those routines using the buffers.  If you pass a

returned pointer to a subroutine, bugs may develop; such data must be processed

locally and soon.  For more durable values use sm_getfield.

 

Menus. You can use sm_menu_proc or sm_choice; the latter returns you the whole

text of the selected menu item, the former only the first character. If you can

design your menus so that each entry is unique in the first character (perhaps

by preceding the entries with labels), sm_menu_proc is easier to use.

sm_mp_string can be used to make sm_menu_proc cooperate with menus whose entries

are not unique in the first character, but then additional processing is

required after the function returns.

 

If your menu is too big to fit on the screen and you want to use scrolling, or

if you need to process the whole menu entry, sm_choice is preferable; it will

search the whole scrolling buffer for a match. sm_menu_proc will only search the

entries that appear on the screen, although it will allow you to scroll through

entries with the PAGE UP and PAGE DOWN keys.

 

Finally, if you wish to recognize function keys as well as menu picks, use

sm_menu_proc; it will return the value of the function key struck, which

sm_choice cannot, since its return value is the text of the field. The JAM

run-time system uses sm_menu_proc for menus with contol fields, and sm_choice

for item selection screens.


 

3 Library Functions by Name

 

An alphabetical list of JAM library functions follows. For each, you will find

several items:

 

   .

      A synopsis similar to a C function declaration, giving the types of the

      arguments and return value.

   .

      A detailed description of the function's arguments, prerequisites,

      results, and side effects.

   .

      The function's return values, if it has any, and their meanings.

   .

      A list of variants and functions that perform related actions, if there

      are any.

   .

      One or two brief coding examples illustrating the function's use. These

      examples have no global framework; where reference is made to external

      functions or variables, their purpose is supposed to be apparent from

      their names, and no more need be read into them.

 

Modules calling JAM library routines should normally include smdefs.h . Those

testing key values returned by sm_openkeybd, sm_menu_proc, or sm_getkey should

include smkeys.h . Include files necessary for specific functions are shown in

the synopsis.


 

NAME

 

     sm_1clear_array - clear all data from an array

 

SYNOPSIS

 

     int sm_1clear_array (field_number)

     int field_number;

 

DESCRIPTION

 

Clears the onscreen and offscreen data of a scrollable array or field. The

buffers that held the offscreen data are not freed, but are blanked. Clears the

onscreen data of a non-scrollable array or field.  This function clears an array

even if it is protected from clearing (CPROTECT). Unlike sm_clear_array, it does

not clear parallel scrolling arrays.

 

RETURNS

 

     -1 if the field was not found; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_1clear_array (field_name);

     sm_clear_array (field_number);

     sm_protect (field_number);

     sm_aprotect (field_number);

 

EXAMPLE

 

/* Clear the totals column of a screen when the field-erase

 * key is pressed. */

 

#include "smdefs.h"

#include "smkeys.h"

 

int key;

 

sm_route_table[FERA] |= RETURN;

...

if (key == FERA)

     sm_n_1clear_array ("totals");


 

NAME

 

     sm_1protect - selectively protect a field

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_1protect (field_number, mask)

     int field_number;

     int mask;

 

DESCRIPTION

 

sm_1protect sets the protection bits to protect the specified field from any

combination of data entry, tabbing into, clearing, or validation. Mnemonics for

mask are defined in smdefs.h , and are listed below. Multiple sets can be done

by oring mnemonics together.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

As an example of combined protections, it is often useful to protect a field

from data entry while still allowing the cursor to enter it (tabbing into). This

is suitable for fields in which one selects an item from a circular scroll list,

or from an item selection screen.

 

sm_1unprotect clears protection bits. sm_protect and its variants set all

protect bits. sm_aprotect sets protection bits for all the fields in an array.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_1protect (field_name, mask);

     sm_e_1protect (field_name, element, mask);

     sm_1unprotect (field_number);

     sm_aprotect (field_number);

     sm_protect (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Protect field number 5 from data entry and clearing,

 * while still allowing the cursor to enter it. */

 

sm_1protect (5, EPROTECT | CPROTECT);


 

NAME

 

     sm_1unprotect - unprotect a field

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_1unprotect (field_number, mask)

     int field_number;

     int mask;

 

DESCRIPTION

 

sm_1unprotect clears protection bits to unprotect the specified field from some

combination of data entry, tabbing into, clearing, or validation.

 

Mnemonics for the mask are defined in smdefs.h , and are listed below. Multiple

sets can be done by oring the mnemonics.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

sm_1protect sets protection bits. sm_protect and related functions set all

protect bits. sm_aprotect sets protection bits for all the fields in an array.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_1unprotect (field_name, mask);

     sm_e_1unprotect (field_name, element, mask);

     sm_1protect (field_number);

     sm_aunprotect (field_number);

     sm_unprotect (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Make field number 5 available for data entry and clearing. */

 

sm_1unprotect (5, EPROTECT | CPROTECT);


 

NAME

 

 

     sm_achg - change the display attribute attached to a scrolling item

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_o_achg (field_number, item_id, disp_attr)

     int field_number;

     int item_id;

     int disp_attr;

 

DESCRIPTION

 

Changes the display attribute attached to a scrollable item. If the item is

onscreen, also changes the attribute with which the item is currently displayed.

Here is a table of attribute mnemonics.

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

If disp_attr is zero, the scrollable display attribute is removed (set to zero).

If the item is onscreen, it is displayed with the attribute attached to its

field.

 

The attribute change this function makes is associated with a data item rather

than a field on a form, and overrides the attribute associated with the field

where the item is displayed (if any). Use sm_chg_attr to change the display

attribute of a field.

 

Note: this function has only two variants, sm_o_achg and sm_i_achg. The other

three variants (including sm_achg itself) do not exist.

 

RETURNS

 

     -1 if the field isn't found or isn't scrollable, or if item_id is invalid;

          0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_o_achg (field_number, item_id, disp_attr);

     sm_i_achg (field_name, item_id, disp_attr);

     sm_chg_attr (field_number, disp_attr);


 

EXAMPLE

 

/* Highlight the data item under the cursor in a scrolling array,

* so that the highlight will move with the item rather than

* staying on the field. */

 

#include "smdefs.h"

 

int base;

int occur;

 

base = sm_base_fldno (sm_getcurno ());

occur = sm_occurno ();

sm_o_achg (base, occur, RED | REVERSE);


 

NAME

 

 

     sm_allget - load screen from the LDB

 

SYNOPSIS

 

     int sm_allget (respect_flag)

     int respect_flag;

 

DESCRIPTION

 

Copies data from the local data block to screen fields with matching names. In

its loop, this function makes use of a data structure set up during screen

display that identifies which fields have LDB entries.

 

If respect_flag is nonzero, this function does not write to fields that already

contain data, or that have their MDT bits set. If the flag is zero, all fields

are initialized. When this function is called by the JAM run-time system, or by

your screen entry function, it does not set MDT bits for the fields it

initializes.

 

This function is similar to the Release 3 function ldb_merge. and is called

automatically by the JAM screen-display logic, unless LDB processing has been

turned off using sm_dd_able. Application code should not normally need to call

it.

 

RETURNS

 

     Always zero.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_lstore (item_name, value);

     sm_dd_able (flag);

 

EXAMPLE

 

#include "smkeys.h"

 

/* If you open a window using sm_r_window, you want named

 * fields initialized from the LDB, and LDB processing is

 * off, you will need to call sm_allget explicitly. You

 * could use this, e.g., to make the LDB read-only during

 * a certain transaction. */

 

sm_dd_able (0);

...

 

if (sm_r_window ("popup", 5, 24) == 0)

{

     sm_allget (0);

     while (sm_openkeybd () != EXIT)

     {

          ...

     }

     sm_close_window ();

}


 

NAME

 

     sm_amt_format - write data to a field, applying currency editing

 

SYNOPSIS

 

     int sm_amt_format (field_number, buffer)

     int field_number;

     char *buffer;

 

DESCRIPTION

 

If the specified field has an amount edit, it is applied to the data in buffer.

If the resulting string is too long for the field, an error message is

displayed. Otherwise, sm_putfield is called to write the edited string to

specified field.

 

If the field has no amount edit, sm_putfield is called with the unedited string.

 

RETURNS

 

     -1 if the field is not found or the item ID is out of range; -2 if the

          edited string will not fit in the field; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_amt_format (field_name, element, buffer);

     sm_i_amt_format (field_name, occurrence, buffer);

     sm_n_amt_format (field_name, buffer);

     sm_o_amt_format (field_number, occurrence, buffer);

     sm_strip_amt_ptr (field_number, text);

     sm_dtofield (field_number, real_value);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Write a list of real numbers to the screen. The first

 * and last fields in the list are tagged with special names.

 * Actually, sm_dtofield () would be more convenient.

 */

int k, first, last;

char buf[256];

double values[];

     /* set up elsewhere... */

 

last = sm_n_fldno ("last");

first = sm_n_fldno ("first");

for (k = first; k && k <= last; ++k)

{

     sprintf (buf, "%lf", values[k - first]);

     sm_amt_format (k, buf);

}


 

NAME

 

     sm_aprotect - protect an array

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_aprotect (field_number, mask)

     int field_number;

     int mask;

 

DESCRIPTION

 

sm_aprotect sets protection bits for every field in the array containing

field_number. The fields are then protected from some combination of data entry,

tabbing into, clearing, or validation, according to mask. If the field is

scrolling, all offscreen items are protected as well.

 

Mnemonics for mask are defined in smdefs.h , and are listed below. Multiple sets

can be done by oring the mnemonics.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

sm_aunprotect clears protection for an array. sm_protect and variants set all

protect bits for a single field. sm_1protect sets protection bits for a single

field; such changes will supersede the array protection for onscreen elements,

but the array protection will remain in effect for offscreen items.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_aprotect (field_name, mask);

     sm_aunprotect(field_number, mask);

     sm_1protect(field_number, mask);

     sm_protect(field_number, mask);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Postpone calculations by protecting the totals column from

* validation; this will prevent execution of its math edit. */

 

sm_n_aprotect ("subtotals", VPROTECT);


 

NAME

 

     sm_ascroll - scroll to a given occurrence

 

SYNOPSIS

 

     int sm_ascroll (field_number, occurrence)

     int field_number;

     int occurrence;

 

DESCRIPTION

 

This function scrolls the designated field so that the indicated occurrence

appears there. The field need not be the first element of a scrolling array; you

could use this function, for instance, to place the nineteenth item in the third

onscreen element of a five-element scrolling array.

 

The validity of certain combinations of parameters depends on the exact nature

of the field. For instance, if field number 7 is the third element of a

scrolling array, the call

 

     sm_ascroll (7, 1);

 

will fail on a regular scrolling array but succeed if scrolling is circular.

 

Parallel arrays or fields will, of course, scroll along with the target array or

field.

 

RETURNS

 

     -1 if field or occurrence specification is invalid, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     int sm_n_ascroll (field_name, occurrence);

     int sm_rscroll (field_number, count);

     int sm_t_scroll (field_number);

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Scroll the "records" array (and those parallel to it)

 * to the line indicated in another field on the screen. */

 

#define GOTO_LINE PF4

 

if (sm_openkeybd () == GOTO_LINE)

{

     sm_n_ascroll ("records", sm_n_intval ("line");

}


 

NAME

 

     sm_aunprotect - unprotect an array

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_aunprotect (field_number, mask)

     int field_number;

     int mask;

 

DESCRIPTION

 

sm_aunprotect clears protection bits for every field in the array containing

field_number, and for scrolling items if the array is scrolling. The fields are

then unprotected from some combination of data entry, tabbing into, clearing, or

validation, according to mask.

 

Mnemonics for mask are defined in smdefs.h , and are listed below. Multiple sets

can be done by oring the mnemonics.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

sm_aprotect sets protection bits. sm_protect and related functions set all

protect bits for a single field. sm_1protect sets protection bits for a single

field; such changes will supersede the array protection for onscreen elements,

but the array protection will remain in effect for offscreen items.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_aunprotect (field_name, mask);

     sm_aprotect(field_number);

     sm_1unprotect(field_number);

     sm_unprotect(field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* open all fields in array number 14 to data entry and clearing */

 

sm_aunprotect (14, EPROTECT | CPROTECT);


 

NAME

 

     sm_backtab - backtab to the previous start of an unprotected field

 

SYNOPSIS

 

     void sm_backtab ();

 

DESCRIPTION

 

If the cursor is in an unprotected field, but not in the first enterable

position, it is moved to the first enterable position of that field. Otherwise,

it is moved to the first enterable position of the previous unprotected field.

If the cursor is in the first position of the first unprotected field on the

form, or before the first unprotected field on the form, it wraps backward into

the last unprotected field. If there are no unprotected fields, the cursor

doesn't move.

 

If the destination field is shiftable, it is reset according to its

justification. Note that the first enterable position depends on the

justification of the field and, in digits-only fields, on the presence of

punctuation.

 

The previous field here means the field with the next lower number; field

numbers increase from left to right within a display line, and from top to

bottom. This function disregards next field edits.

 

EXAMPLE

 

#include "smkeys.h"

 

/* Back the cursor up if the user strikes a key indicating

 * s/he has made a particular mistake. */

int key;

 

do {

     key = sm_openkeybd ();

     if (key == PF5)

     {

          sm_quiet_err ("OK, start over");

          sm_backtab ();

     }

} while (key != EXIT && key != XMIT);


 

NAME

 

     sm_base_fldno - get the field number of the first element of an array

 

SYNOPSIS

 

     int sm_base_fldno (field_number)

     int field_number;

 

DESCRIPTION

 

If the field specified by field_number is an array element, this function

returns the field number of the first element (base) of the array.

 

If the field is not an array element, it returns field_number.

 

RETURNS

 

     The field number of the base element of the array containing the specified

          field, or 0 if the field number is out of range.

 

VARIANTS AND RELATED FUNCTIONS

 

EXAMPLE

 

#include "smdefs.h"

 

/* Highlight the data item under the cursor in a scrolling array,

 * so that the highlight will move with the item rather than

 * staying on the field. */

 

int base;

int occur;

 

base = sm_base_fldno (sm_getcurno ());

occur = sm_occur_no ();

sm_o_achg (base, occur, RED | REVERSE);

sm_gofield (base);


 

NAME

 

     sm_bel - beep!

 

SYNOPSIS

 

     void sm_bel ()

 

DESCRIPTION

 

Causes the terminal to beep, ordinarily by transmitting the ASCII BEL code to

it. If there is a BELL entry in the video file, sm_bel will transmit that

instead, usually causing the terminal to flash instead of beeping.

 

Even if there is no BELL entry, use this function instead of sending a BEL,

because certain displays use BEL as a graphics character.

 

Including a %B at the beginning of a message displayed on the status line will

cause this function to be called.

 

EXAMPLE

 

#include "smkeys.h"

 

/* Beep at unwanted function keys. */

int key;

 

switch (key = sm_openkeybd ())

{

     case PF1:

          save_something ();

          break;

     case PF2:

          discard_something ();

          break;

     default:

          sm_bel();

          break;

}


 

NAME

 

     sm_bitop - manipulate validation and data editing bits

 

SYNOPSIS

 

     #include "smbitops.h"

 

     int sm_bitop(field_number, action, bit)

     int field_number;

     int action;

     int bit;

 

DESCRIPTION

 

You can use this function to inspect and modify validation and data editing bits

of screen fields, without reference to internal data structures. The first

parameter identifies the field to be operated upon.

 

Action can include a test and at most one manipulation, from the following table

of mnemonics:

 

     Mnemonic       Meaning

 

     BIT_CLR        Turn bit off BIT_SET

                    Turn bit on BIT_TOGL

                    Flip state of bit BIT_TST

                    Report state of bit

 

The third parameter is a bit identifier, drawn from the following table:

 

     Character edits

 

     N_ALL          N_DIGIT N_YES_NO

                    N_ALPHA N_NUMERIC

                    N_ALPHNUM N_FCMASK

 

     Field edits

 

     N_RTJUST       N_REQD N_VALIDED

                    N_MDT N_CLRINP

                    N_MENU N_UPPER

                    N_LOWER N_RETENTRY

                    N_FILLED N_NOTAB

                    N_WRAP N_EPROTECT

                    N_TPROTECT N_CPROTECT

                    N_VPROTECT N_ALLPROTECT

                    N_ADDLEDS

 

The character edits are not, strictly speaking, bits; you cannot toggle them,

but the other functions work as you would expect. N_ALLPROTECT is a special

value meaning all four protect bits at once.

 

N_VALIDED and N_MDT are the only bit operations that can apply offscreen. All

other bit operations are attached to fixed onscreen positions.

 

This function has two variants, sm_a_bitop and sm_t_bitop, which perform the

requested bit operation on all elements of an array. Their synopses appear

below. If you include BIT_TST, these variants return 1 only if bit is set for

every element of the array. The variants sm_i_bitop and sm_o_bitop are

restricted to N_VALIDED and N_MDT.


 

RETURNS

 

     -1 if the field or occurrence cannot be found; -2 if the action or bit

          identifiers are invalid; 1  if there was no error, the action included

          a test  operation, and bit was set; -3  if sm_i_bitop or sm_o_bitop

          were called with bit set to something other than N_VALIDED or N_MDT;

          0  otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_bitop (array_name, element, action, bit);

     sm_i_bitop (array_name, occurrence, action, bit);

     sm_n_bitop (field_name, action, bit);

     sm_o_bitop (field_number, occurrence, action, bit);

 

     sm_a_bitop (array_name, action, bit);

     sm_t_bitop (array_number, action, bit);

 

EXAMPLE

 

#include "smbitops.h"

 

/* Check whether a field is valid. If not, place the

 * cursor there. */

 

if (! sm_n_bitop ("operation", BIT_TST, N_VALIDED))

{

     sm_n_gofield ("operation");

}

 

/* Make the array "quantities" required. */

 

sm_a_bitop (sm_n_fldno ("quantities"), BIT_SET, N_REQD);


 

NAME

 

     sm_c_off - turn the cursor off

 

SYNOPSIS

 

     void sm_c_off ();

 

DESCRIPTION

 

This function notifies JAM that the normal cursor setting is off. The normal

setting is in effect except when a block cursor is in use, as during menu

processing (cursor off); while screen manager functions are writing to the

display (cursor off); and within certain error message display functions (cursor

on).

 

If the display cannot turn its cursor on and off (CON and COF entries are not

defined in the video file), this function will have no effect.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_c_on ();

 

EXAMPLE

 

     sm_err_reset("Verify that the cursor is turned ON");

     sm_c_off();

     sm_emsg("Verify that the cursor is turned OFF");

     sm_c_on();

     sm_emsg("Verify that the cursor is turned ON");


 

NAME

 

     sm_c_on - turn the cursor on

 

SYNOPSIS

 

     void sm_c_on ();

 

DESCRIPTION

 

This function notifies JAM that the normal cursor setting is on. The normal

setting is in effect except when a block cursor is in use, as during menu

processing (cursor off); while screen manager functions are writing to the

display (cursor off); and within certain error message display functions (cursor

on).

 

If the display cannot turn its cursor on and off (CON and COF entries are not

defined in the video file), this function will have no effect.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_c_off ();

 

EXAMPLE

 

     sm_err_reset("Verify that the cursor is turned ON");

     sm_c_off();

     sm_emsg("Verify that the cursor is turned OFF");

     sm_c_on();

     sm_emsg("Verify that the cursor is turned ON");


 

NAME

 

     sm_c_vis - turn cursor position display on or off

 

SYNOPSIS

 

     void sm_c_vis (disp)

     int disp;

 

DESCRIPTION

 

If disp is non-zero, subsequent messages displayed on the status line, including

background status messages, will include the cursor's screen position. If the

message would overlap the cursor position display, it is truncated. If disp is

zero, subsequent messages displayed on the status line will not include the

cursor's position.

 

If the CURPOS entry in the video file is not defined, this function will have no

effect; the cursor position will not appear. JAM uses an asynchronous function

and a status line function to perform the cursor position display; if the

application has previously installed either of those, this function will clobber

it.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_u_async ();

     sm_u_statfnc ();

     sm_install (which_hook, what_func, howmany);

 

EXAMPLE

 

#include "smkeys.h"

 

/* Toggle the cursor position display on or off when the

* PF10 key is struck. The first time the key is struck,

* it will go on. */

 

static int cpos_on = 0;

 

switch (sm_openkeybd ())

{

...

case PF10:

     sm_c_vis (cpos_on ^= 1);

...

}


 

NAME

 

     sm_calc - perform a calculation

 

SYNOPSIS

 

     int sm_calc (field_number, item_id, expression)

     int field_number;

     int item_id;

     char *expression;

 

DESCRIPTION

 

The field_number and item_id parameters identify the field and item with which

the calculation is associated. (If the field is not scrollable, item_id should

be set to zero.) Expression is a calculation, written as specified in the JAM

Author's Guide. Briefly, a calculation contains an optional precision specifier,

%m.n; a destination field identifier; an equal sign; and a math expression. The

expression uses conventional arithmetic operators and parentheses in infix

notation, with a few special unary operators. It and the destination field

identifier may specify fields by name, absolute number, or relative number.

 

If the calculation begins with % the rounding information is extracted.

Otherwise, rounding information is taken from the float or double data type

edit, if any, attached to the destination field; or from the amount edit, if

any, attached to the destination field. If none of the above are available, the

default rounding to 2 decimal places is performed.

 

If the destination field is a date field, the value of the expression is

formatted as a date. sm_calc provides a way of placing arbitrary dates in

fields, through the @date expression. You should call sm_calc with an argument

in the following form:

 

     destination-field = @date (your-date)

 

where destination-field identifies a field by name or number as defined in the

Author's Guide, and your-date is formatted as MM/DD/YYYY; assuming that the

destination field is a date field, it will be written out in the proper format.

This is presently the only way of getting an arbitrary date, properly formatted,

into a date field.

 

If a math error such as divide by zero or wrong date format occurs, a message is

presented to the operator, and the function returns -1.

 

RETURNS

 

     -1 is returned if a math error occurred. 0 is returned otherwise.

 

EXAMPLE

 

/* Place a famous date in a field. */

 

sm_calc ("day1 = @date(07/04/1776)");


 

NAME

 

     sm_cancel - reset the display and exit

 

SYNOPSIS

 

     void sm_cancel ();

 

DESCRIPTION

 

This routine is installed by sm_initcrt to be executed if a keyboard interrupt

occurs. It calls sm_resetcrt to restore the display to the operating system's

default state, and exits to the operating system.

 

If your operating system supports it, you can also install this function to

handle conditions that normally cause a program to abort. If a program aborts

without calling sm_resetcrt, you may find your terminal in an odd state;

sm_cancel can prevent that.

 

EXAMPLE

 

/* the following program segment could be found in some

 * error routines */

 

if (error)

{

     sm_quiet_err("fatal error -- can't continue!\n");

     sm_cancel();

}

 

 

/* The following code can be used on a UNIX system to

 * install sm_cancel() as a signal handler. */

 

#include <signal.h>

 

extern void sm_cancel ();

 

signal (SIGTERM, sm_cancel);


 

NAME

 

     sm_ch_emsgatt - change the standard error message attributes

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_ch_emsgatt (noisy_att, quiet_att)

     int noisy_att, quiet_att;

 

DESCRIPTION

 

Changes the display attributes used by sm_err_reset and sm_quiet_err. Noisy_att

is used for the message by sm_err_reset and for the message prefix (normally

"ERROR:") displayed by sm_quiet_err. Quiet_att is used for the message body

displayed by sm_quiet_err.

 

If either argument is zero, the corresponding display attribute is unchanged. If

an argument is nonzero but no color is specified, and the display does not

support background color, the color is made WHITE.

 

The following display attribute mnemonics may be used in the arguments to this

function:

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

If sm_ch_emsgatt is never called, sm_err_reset uses WHITE with BLINK, and

HILIGHT if it is available. The default attribute for the message body displayed

by sm_quiet_err is just WHITE.

 

If you define the SMCHEMSGATT variable in your setup file, this function will

automatically be called with the parameters you provide there.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_err_reset (message);

     sm_quiet_err(message);

     sm_er_options (key, discard);

 

EXAMPLE

 

#include "smdefs.h"

 

sm_ch_emsgatt(NORMAL_ATTR, NORMAL_ATTR);

sm_err_reset("Verify this message is displayed in white.");

 

sm_ch_emsgatt(REVERSE, NORMAL_ATTR);

sm_err_reset("Verify this message is in reverse video.");


 

NAME

 

     sm_ch_form_atts - change the standard JAM library window attributes

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_ch_form_atts (bord_style, bord_attr,

          protect_attr, entry_attr)

          int bord_style;

          int bord_attr;

          int protect_attr;

          int entry_attr;

 

DESCRIPTION

 

Changes the display characteristics of windows that are part of the library.

Currently, there are four such windows: the system calls (SPF2) window; the

go-to-screen (SPF3) window; the error window, used to display a message too long

to fit on the status line; and the hit space window, which pops up if you hit

the wrong key to acknowledge an error message.

 

This function is intended to be called once, at the beginning of an application,

to set the display characteristics of the library windows to harmonize with the

application's own forms.

 

If bord_style is less than 0, the windows are made borderless. Otherwise, it is

made the border style number (0 through 9), and border_attribute, if nonzero, is

made the border attribute.

 

If protect_attr is nonzero, it is used for protected fields that contain

messages. If entry_attr is nonzero, it is used for the unprotected data entry

fields.

 

If you define the SMCHFORMATTS variable in your setup file, this function will

automatically be called with the parameters you provide there.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Give the library windows a colorless graphics border

* (conventionally style 1), with yellow message fields and

* green data entry field. */

 

sm_ch_form_atts (1, NORMAL_ATTR, YELLOW, GREEN);


 

NAME

 

     sm_ch_qmsgatt - change the standard query message attribute

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_ch_qmsgatt (disp_attr)

     int disp_attr;

 

DESCRIPTION

 

Changes the display attribute used by sm_query_msg. If no color is specified, it

is set to WHITE.

 

The argument disp_attr is the logical sum of one or more of the following:

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

If sm_ch_qmsgatt is never called, sm_query_msg uses WHITE and REVERSE, with

HILIGHT if it is available.

 

If you define the SMCHQMSGATT variable in your setup file, this function will

automatically be called with the parameters you provide there.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_query_msg (question);

 

EXAMPLE

 

#include "smdefs.h"

 

sm_ch_qmsgatt(NORMAL_ATTR);

sm_query_msg("Verify that this message is displayed in white.");

 

sm_ch_qmsgatt(GREEN);

sm_query_msg("Verify that this message is displayed in green.");


 

NAME

 

     sm_ch_stextatt - change the status text display attribute

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_ch_stextatt (disp_attr)

     int disp_attr;

 

DESCRIPTION

 

Changes the display attribute used for displaying status text associated with a

field. If no color is specified, it is set to WHITE.

 

The argument disp_attr is the logical sum of one or more of the following:

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

If sm_ch_stextatt is never called, the display attribute used for the status

text associated with a field is normal intensity WHITE.

 

If you define the SMCHSTEXTATT variable in your setup file, this function will

automatically be called with the parameters you provide there.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Change the default status text attribute to bright green. */

 

sm_ch_stextatt (GREEN | HILIGHT);


 

NAME

 

     sm_chg_attr - change the display attribute of a field

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_chg_attr (field_number, disp_attr)

     int field_number, disp_attr;

 

DESCRIPTION

 

Changes the display attribute of a field. If the field is scrolling, each data

item may also have a display attribute, which will override the field display

attribute when the item arrives onscreen; use sm_achg to change scrolling

attributes.

 

Disp_attr is the logical sum of one or more of the following. If no color is

specified, and BLACK is not a valid color, sm_chg_attr will automatically

include the color WHITE.

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_chg_attr (field_name, disp_attr);

     sm_e_chg_attr (field_name, element, disp_attr);

     sm_o_chg_attr (field_number, occurrence, disp_attr);

     sm_i_achg (field_name, item_id, disp_attr);

     sm_o_achg (field_number, item_id, disp_attr);

 

EXAMPLE

 

#include "smdefs.h"

 

sm_chg_attr (1, NORMAL_ATTR);

sm_err_reset ("Verify that the text in field 1 is white.");

 

sm_chg_attr (1, BLANK);

sm_err_reset ("Verify that the text in field 1 is invisible.");


 

NAME

 

     sm_choice - get item selection

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_choice (type)

     int type;

 

DESCRIPTION

 

This is a menu-handling function, similar in some respects to sm_menu_proc. It

enables you to tab, backtab, arrow and scroll through a screen, in order to

select the contents of one of the fields or scrolling items. The entry at which

the cursor is positioned is shown in reverse video; fields that are blank in

their first position, and those without a MENU field edit, will be skipped.

 

Hitting a key that matches the first character of a screen entry causes the

cursor to be positioned there; if more than one entry begins with that

character, the cursor is positioned to the first entry following its current

location. Entries are searched by field number. Arrays and scrolls, however, are

searched in their entirety following their first field, and scrolling occurs

automatically. If type is UPPER (or LOWER), an alphabetic key is translated to

upper (or lower) case before a match is attempted; if it is UPPER | LOWER, both

are tried; and if type has any other value, the entry is not translated.

 

sm_choice returns to the calling program only when you hit the TRANSMIT or EXIT

key. It ignores menu return codes attached to fields; the returned value is the

result of a call to sm_fptr.

 

The functions sm_mp_options and sm_mp_string, which control the behavior of

sm_menu_proc, do not affect sm_choice.

 

Menu control strings are not executed within this function, but at a higher

level of the JAM run-time system. If you call this function, do not expect your

selection's control string to be executed.

 

 

RETURNS

 

     The contents of the selected field if TRANSMIT was hit, or 0 if EXIT was

          hit.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_menu_proc (type);

     sm_fptr (field_number);


 

EXAMPLE

 

#include "smdefs.h"

#define WHI    WHITE | HILIGHT

#define NOT_UL ~(UPPER|LOWER)

 

#define INS1 "Move cursor to 2nd field and press TRANSMIT"

#define INS5 "Press 'c' and TRANSMIT"

 

/* Move the cursor to the second field

 * and press the TRANSMIT key. Verify that a pointer

 * to the text of the second field is returned. */

 

sm_d_msg_line(INS1,WHI);

if (strcmp("bcdefgh", sm_choice(NOT_UL)))

     sm_err_reset ("Bad choice");

 

/* Press the first letter of the first item of

 * the third field ("c" or "C") and verify that the

 * cursor is located correctly. */

 

sm_d_msg_line(INS5,WHI);

if (strcmp("CDE", sm_choice(UPPER)))

     sm_err_reset ("Bad choice");


 

NAME

 

     sm_cl_all_mdts - clear all MDT bits

 

SYNOPSIS

 

     void sm_cl_all_mdts ();

 

DESCRIPTION

 

Clears the MDT (modified data tag) of every data item, both onscreen and off.

 

JAM sets the MDT bit of an occurrence to indicate that it has been modified,

either by keyboard entry or by a call to a function like sm_putfield, since the

screen was first displayed.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_mdt_clear (field_number);

     sm_mod_test (field_number);

     sm_tst_all_mdts (field_number, occurrence);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Clear MDT for all fields on the form; then write

 * data to the last field, and check that its MDT is

 * the first one set. */

 

int occurrence;

 

sm_cl_all_mdts();

sm_putfield (sm_numflds, "Hello");

if (sm_tst_all_mdts (&occurrence) != sm_numflds)

     sm_err_reset ("Something is rotten in the state of Denmark.");


 

NAME

 

     sm_cl_everyfield - clear all fields, protected or not

 

SYNOPSIS

 

     void sm_cl_everyfield ();

 

DESCRIPTION

 

Erases all fields on the current screen, including protected fields and

offscreen data. Date and time fields that take system values are re-initialized.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_cl_unprot ();

 

EXAMPLE

 

/* The following code effectively binds sm_cl_everyfield

 * to the CLEAR ALL key, instead of sm_cl_unprot (the

 * normal binding). */

 

#include "smdefs.h"

#include "smkeys.h"

 

int key;

 

/* Make the CLEAR ALL key returnable and NOT executable. */

sm_route_table[CLR] = RETURN;

 

while ((key = sm_openkeybd ()) != EXIT)

{

     if (key == CLR)

     {

          sm_cl_everyfield ();

          continue;

     }

     ...

}


 

NAME

 

     sm_cl_unprot - clear all unprotected fields

 

SYNOPSIS

 

     void sm_cl_unprot ();

 

DESCRIPTION

 

Erases onscreen and offscreen data from all fields that are not protected from

clearing (CPROTECT). Date and time fields that take system values are

re-initialized.

 

This function is normally bound to the CLEAR ALL key.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_cl_everyfield ();

     sm_1protect (field_number);

 

EXAMPLE

 

/* The following code clears all unprotected fields and puts

 * the cursor into the first one. */

 

sm_cl_unprot ();

sm_home ();


 

NAME

 

     sm_clear_array - erase all data from an array

 

SYNOPSIS

 

     int sm_clear_array (field_number)

     int field_number;

 

DESCRIPTION

 

Clears onscreen and offscreen data of the specified array or field. If there are

scrollable arrays or fields parallel to the one specified, they are also

cleared.

 

The array indicated by the argument will be cleared regardless of protection;

the protection of parallel scrolling arrays will, however, be respected.

 

The buffers that held the offscreen data are freed and are no longer accessible.

 

RETURNS

 

     -1 if the field is not found; -2 if memory allocation fails; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_clear_array (field_name);

     sm_1clear_array (field_number);

     sm_aprotect (field_number);

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Make the ERASE key clear the entire array of "names",

 * first ensuring that it will be returned to us. */

 

int key;

 

sm_route_table[FERA] |= RETURN;

 

while ((key = sm_openkeybd ()) != EXIT)

{

     if (key == FERA)

          sm_n_clear_array ("names");

}


 

NAME

 

     sm_close_window - close current window

 

SYNOPSIS

 

     int sm_close_window ();

 

DESCRIPTION

 

The currently open window is erased, and the screen is restored to the state

before the window was opened. All data from the window being closed is lost

unless LDB processing is active, in which case named fields are copied to the

LDB using sm_lstore. Since windows are stacked, the effect of closing a window

is to return to the previous window. The cursor reappears at the position it had

before the window was opened.

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     -1 is returned if there is no window open, i.e. if the currently displayed

          screen is a form (or if there is no screen up). 0 is returned

          otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_window (screen_name, line, column);

     sm_d_window (address, line, column);

     sm_l_window (library_descriptor, screen_name, line, column);

     sm_wselect (window_num);


 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* In a validation routine, if the field contains a

 * special value, open up a window to prompt for a

 * second value and save it in another field. */

 

int validate (field, data, occur, bits)

char *data;

{

     char buf[256];

 

     if (bits & VALIDED)

          return 0;

 

     if (strcmp(data, "other") == 0)

     {

          sm_r_at_cur ("getsecval");

          if (sm_openkeybd () != EXIT)

               sm_getfield (buf, 1);

          else buf[0] = 0;

          sm_close_window ();

          sm_n_putfield ("secval", buf);

     }

 

     return 0;

}


 

NAME

 

     sm_d_at_cur - display a memory-resident window at the current cursor

                   position

 

SYNOPSIS

 

     int sm_d_at_cur (mr_screen)

     char *mr_screen;

 

DESCRIPTION

 

Displays a memory-resident window at the current cursor position, offset by one

line to avoid hiding that line's current display. Mr_screen is the address of

the screen in memory.

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

You can use JYACC bin2c to convert screens from disk files, which you can modify

using jxform, to program data structures you can compile into your application.

A memory-resident screen is never altered at run-time, and may therefore be made

shareable on systems that provide for sharing read-only data. sm_r_at_cur can

also display memory-resident screens, if they are properly installed using

sm_formlist. Memory-resident screens are particularly useful in applications

that have a limited number of screens, or in environments that have a slow disk

(e.g. MS-DOS).

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 is returned if no error occurred during display of the form; -3 is

          returned if no memory was available; -7 is returned if the screen

          contained fields that would not fit within the physical display. The

          screen is always restored to its previous condition.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_form (mr_screen);

     sm_d_window (mr_screen, line, column);

     sm_r_at_cur (name);


 

EXAMPLE

 

/* Display a warning message in a memory-resident window,

 * and wait for acknowledgement before continuing.

 * The warning should include the instruction,

 * "Press any key to continue." */

 

extern char warning[];

 

if (over_threshold ())         /* Externally defined condition */

{

     sm_d_at_cur (warning);

     sm_getkey ();

     sm_close_window ();

}

...


 

NAME

 

     sm_d_form - display a memory-resident form

 

SYNOPSIS

 

     int sm_d_form (mr_screen)

     char *mr_screen;

 

DESCRIPTION

 

This function displays a memory-resident screen as a base form. Mr_screen is the

address of the screen.

 

Bringing up a screen as a form causes the previously displayed form and windows

to be discarded, and their memory freed. The new screen is displayed with its

upper left-hand corner at the extreme upper left of the display (position (0,

0)). Any error in this function leaves the display and JAM internals in an

undefined state.

 

If the form contains display data that are too big for the physical display,

they are truncated without warning. However, if there are fields that won't fit

within the physical display, this function returns an error without displaying

the form.

 

You can use JYACC bin2c to convert screens from disk files, which you can modify

using jxform, to program data structures you can compile into your application.

A memory-resident screen is never altered at run-time, and may therefore be made

shareable on systems that provide for sharing read-only data. sm_r_at_cur can

also display memory-resident screens, if they are properly installed using

sm_formlist. Memory-resident screens are particularly useful in applications

that have a limited number of screens, or in environments that have a slow disk

(e.g. MS-DOS).

 

This function should be called by JAM applications only under unusual

circumstances, as it does not update the control stack. You should execute a

control string to display the form instead.

 

RETURNS

 

     0 is returned if no error occurred during display of the screen. -5 is

          returned if, after the screen was cleared, the system ran out of

          memory. -7 is returned if the screen contained fields that would not

          fit within the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_window (mr_screen, line, column)

     sm_d_at_cur (mr_screen)

     sm_r_form (screen_name)

     sm_l_form (library_descriptor, screen_name)


 

EXAMPLE

 

/* Display a memory-resident form to provide a

 * blank background for what follows. */

 

extern char blank[];

 

if (sm_d_form (blank) < 0)

{

     sm_err_reset ("Error in form display - goodbye!");

     sm_cancel ();

}

...


 

NAME

 

     sm_d_msg_line - display a message on the status line

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_d_msg_line (message, attrib)

     char *message;

     int attrib;

 

DESCRIPTION

 

The message in message is displayed on the status line, with an initial display

attribute of attrib. This message overrides background status text and field

status text; it will itself be overwritten by sm_err_reset and related

functions, or by the ready/wait message enabled by sm_setstatus.

 

Several percent escapes provide control over the content and presentation of

status messages. They are interpreted by sm_d_msg_line, which is eventually

called by everything that puts text on the status line (including field status

text). The character following the percent sign must be in upper-case; this is

to avoid conflict with the percent escapes used by printf and its variants.

Certain percent escapes (%W, for instance; see below) must appear at the

beginning of the message, i.e. before anything except perhaps another percent

escape.

 

   .

      If a string of the form %Annnn appears anywhere in the message, the

      hexadecimal number nnnn is interpreted as a display attribute to be

      applied to the remainder of the message. The table below gives the

      numeric values of the logical display attributes you will need to

      construct embedded attributes. If you want a digit to appear

      immediately after the attribute change, pad the attribute to 4 digits

      with leading zeroes; if the following character is not a legal hex

      digit, leading zeroes are unnecessary.

   .

      If a string of the form %KKEYNAME appears anywhere in the message,

      KEYNAME is interpreted as a logical key mnemonic, and the whole

      expression is replaced with the key label string defined for that key

      in the key translation file. If there is no label, the %K is stripped

      out and the mnemonic remains. Key mnemonics are defined in smkeys.h ;

      it is of course the name, not the number, that you want here. The

      mnemonic must be in upper-case.

   .

      If %N appears anywhere in the message, the latter will be presented in

      a pop-up window rather than on the status line, and all occurrences of

      %N will be replaced by newlines.

   .

      If the message begins with a %B, JAM will beep the terminal (using

      sm_bel) before issuing the message.

   .

      If the message begins with %W, it will be presented in a pop-up window

      instead of on the status line. The window will appear near the bottom

      center of the screen, unless it would obscure the current field by so

      doing; in that case, it will appear near the top.  If the message

      begins with %MU or %MD, and is passed to one of the error message

      display functions, JAM will ignore the default error message

      acknowledgement flag and process (for %MU) or discard (for %MD) the

      next character typed.


 

Note that, if a message containing percent escapes - that is, %A, %B, %K, %N or

%W - is displayed before sm_initcrt or after %W is called, the percent escapes

will show up in it.

 

            Attribute               Hex value

 

          BLACK               0 BLUE

                              1 GREEN

                              2 CYAN

                              3 RED

                              4 MAGENTA

                              5 YELLOW

                              6 WHITE

                              7

 

          B_BLACK             0 B_BLUE

                              100 B_GREEN

                              200 B_CYAN

                              300 B_RED

                              400 B_MAGENTA

                              500 B_YELLOW

                              600 B_WHITE

                              700

 

          BLANK               8 REVERSE

                              10 UNDERLN

                              20 BLINK

                              40 HILIGHT

                              80 DIM

                              1000

 

If the cursor position display has been turned on (see sm_c_vis), the end of the

status line will contain the cursor's current row and column. If the message

text would overlap that area of the status line, it will be displayed in a

window instead.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_err_reset (message);

     sm_msg (message, start_column);

     sm_mwindow (text, line, column);

 

EXAMPLE

 

/* The following prompt uses labels for the EXIT and

 * return keys, and underlines crucial words. */

 

sm_d_msg_line ("Press %KEXIT to %A0027abort%A7, or %KNL to %A0027continue%A7.");

 

/* To clear the message line, use: */

 

sm_d_msg_line ("", 0);


 

NAME

 

     sm_d_window - display a memory-resident window at a stated position

 

SYNOPSIS

 

     int sm_d_window (mr_screen, line, column)

     char *mr_screen;

     int line, column;

 

DESCRIPTION

 

The memory-resident screen whose address is in mr_screen is brought up with its

upper left-hand corner at (line, column). The line and column are counted from

zero: if line is 1, the screen is displayed starting at the second line of the

screen. Note that the window coordinates you place in JAM control strings are

counted from 1 as usual.

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

You can use JYACC bin2c to convert screens from disk files, which you can modify

using jxform, to program data structures you can compile into your application.

A memory-resident screen is never altered at run-time, and may therefore be made

shareable on systems that provide for sharing read-only data. sm_r_at_cur can

also display memory-resident screens, if they are properly installed using

sm_formlist. Memory-resident screens are particularly useful in applications

that have a limited number of screens, or in environments that have a slow disk

(e.g. MS-DOS).

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 is returned if no error occurred during display of the screen. -5 is

          returned if, after the screen was cleared, the system ran out of

          memory. -7 is returned if the screen contained fields that would not

          fit within the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_at_cur (mr_screen);

     sm_d_form (mr_screen);

     sm_r_window (screen_name, line, column);

     sm_l_window (library_descriptor, screen_name, line, column);


 

EXAMPLE

 

/* Display a warning message in a memory-resident

 * window centered on the screen, and

 * wait for acknowledgement before continuing. */

 

extern char warning[];

 

if (over_threshold ())         /* Externally defined condition */

{

     sm_d_window (warning, 8, 18);

     sm_err_reset ("Press any key to continue");

     sm_close_window ();

}

...


 

NAME

 

     sm_dblval - get the value of a field as a real number

 

SYNOPSIS

 

     #include "smdefs.h"

 

     double sm_dblval (field_number)

     int field_number;

 

DESCRIPTION

 

This function returns the contents of field_number as a real number. It calls

sm_strip_amt_ptr to remove superfluous amount editing characters before

converting the data.

 

RETURNS

 

     The real value of the field is returned. If the field is not found, the

          function returns 0.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_dblval (field_name, element);

     sm_i_dblval (field_name, occurence);

     sm_n_dblval (field_name);

     sm_o_dblval (field_number, occurrence);

     sm_dtofield (field_number, value, format);

     sm_strip_amt_ptr (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Retrieve the value of a starting parameter. */

 

double param1;

 

param1 = sm_n_dblval ("param1");


 

NAME

 

     sm_dd_able - turn LDB write-through on or off

 

SYNOPSIS

 

     void sm_dd_able (flag)

     int flag;

 

DESCRIPTION

 

During normal JAM processing, named fields in the screen and local data block

are kept in sync. When a screen is brought up, values are copied in from the

LDB; when control passes from the screen, values are copied back to the LDB.

When application code reads or writes a value to or from a name that is not in

the screen, JAM accesses the LDB instead.

 

sm_dd_able turns that feature off or on, according to the value of flag. It is

on by default; when it is off, the LDB is never accessed. Refer to Section 9 for

a full explanation.

 

EXAMPLE

 

/* Turn LDB write-through off. */

 

sm_dd_able (0);


 

NAME

 

     sm_dicname - set data dictionary name

 

SYNOPSIS

 

     int sm_dicname (dictionary_name)

     char *dictionary_name;

 

DESCRIPTION

 

This function names the application's data dictionary, which is data.dic by

default. It must be called before JAM initialization, in particular before

sm_ldb_init is called to initialize the local data block from the data

dictionary. The argument dictionary_name is a character string giving the

filename; JAM will search for it in all the directories in the SMPATH variable.

 

You can achieve the same effect by defining the SMDICNAME variable in your setup

file equal to the data dictionary name. See the section on setup files in the

Configuration Guide.

 

RETURNS

 

     -1 if it fails to allocate memory to store the name, 0 otherwise.

 

EXAMPLE

 

/* Set the name of the application's data dictionary to

* /usr/app/common.dic .*/

 

sm_dicname ("/usr/app/common.dic");


 

NAME

 

     sm_disp_off - get displacement of cursor from start of field

 

SYNOPSIS

 

     int sm_disp_off ();

 

DESCRIPTION

 

Returns the difference between the first column of the current field and the

current cursor location. This routine ignores offscreen data; use sm_sh_off to

obtain the total cursor offset of a shiftable field.

 

RETURNS

 

     The difference between cursor position and start of field, or -1 if the

          cursor is not in a field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_sh_off ();

     sm_getcurno ();

 

EXAMPLE

 

/* Retrieve the contents of the current field, up to

 * the cursor position, discarding the rest. This

 * example assumes the field is non-shifting and

 * left-justified. */

 

char buf[256];

int index;

 

sm_getfield (buf, sm_getcurno ());

if ((index = sm_disp_off ()) >= 0)

     buf[index] = '\0';


 

NAME

 

     sm_dlength - get the length of a field's contents

 

SYNOPSIS

 

     int sm_dlength (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the length of data stored in field_number. The length does not include

leading blanks in right justified fields, or trailing blanks in left-justified

fields (which are also ignored by sm_getfield). It does include data that have

been shifted offscreen.

 

RETURNS

 

     Length of field contents, or -1 if the field is not found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_dlength (field_name, element);

     sm_i_dlength (field_name, occurrence);

     sm_n_dlength (field_name);

     sm_o_dlength (field_number, occurrence);

     sm_length (field_number);

 

EXAMPLE

 

/* Save the contents of the "rank" field in a buffer

 * of the proper size. */

 

char *save_rank;

 

if ((save_rank = malloc (sm_n_dlength ("rank") + 1)) == 0)

     punt ("Malloc error");

sm_n_getfield (save_rank, "rank");


 

NAME

 

     sm_do_region - rewrite part or all of a screen line

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_do_region (line, column, length, attribute,

          text)

     int line, column, length, attribute;

     char *text;

 

DESCRIPTION

 

The screen region defined by line, column, and length is rewritten. Line and

column are counted from zero, with (0, 0) the upper left-hand corner of the

screen. If text is zero, the actual text that is written is taken from the

screen buffer; if text is shorter than length, it is padded out with blanks. In

any case, the display attribute of the whole area is changed to attribute. A

table of attribute mnemonics follows.

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

The fifth argument, if passed as zero, must be cast, as in

 

     sm_do_region (line, col, length, attrib, (char *)0);

 

EXAMPLE

 

#include "smdefs.h"

#include "smvideo.h"

 

/* Place a centered text string in a part of the screen where

 * there is (hopefully) no field. The line number is

 * made zero-relative. */

 

void centerstring (text, line)

char *text;

{

     int offset, length = strlen (text);

 

     offset = (*sm_video[V_COLMS] - length) / 2;

     if (offset < 0)

          return;

     sm_do_region (line - 1, offset, length, REVERSE | WHITE, text);

}


 

NAME

 

 

     sm_doccur - delete occurrences

 

SYNOPSIS

 

     int sm_o_doccur (field_number, occurrence, count);

     int field_number;

     int occurrence;

     int count;

 

DESCRIPTION

 

Deletes count data items beginning with the specified occurrence, moving all

following occurrences up. If there are not enough occurrences, fewer than the

requested number will be deleted. The memory associated with the deleted data

items is released. If count is negative, occurrences are inserted instead,

subject to limitations explained at sm_ioccur.

 

If occurrence is zero, the occurrence used is that of field_number. If

occurrence is nonzero, however, it is taken relative to the first field of the

array in which field_number occurs.

 

This function is normally bound to the DELETE LINE key. It has only the o_ and

i_ variants; the others, including sm_doccur itself, do not exist.

 

RETURNS

 

     -1 if the field or occurence number was out of range; -3 if insufficient

          memory was available; otherwise, the number of occurrences actually

          deleted (zero or more).

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_i_doccur(field_name, occurrence, count);

     sm_i_ioccur(field_name, occurrence, count);

     sm_o_ioccur(field_number, occurrence, count);


 

NAME

 

     sm_dtofield - write a real number to a field

 

SYNOPSIS

 

     int sm_dtofield (field_number, value, format)

     int field_number;

     double value;

     char *format;

 

DESCRIPTION

 

The real number value is converted to human-readable form, according to format,

and moved into field_number via a call to sm_amt_format. If the format string is

null, the number of decimal places will be taken from a data type edit, if one

exists; failing that, from a currency edit, if one exists; or failing that, will

default to 2.

 

The format string is in the style of the C library function printf, q.v. It

should have the form %m.nf, where m is the total output width, n is the number

of decimal places, and both are optional.

 

RETURNS

 

     -1 is returned if the field is not found. -2 is returned if the output

          would be too wide for the destination field. 0 is returned otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_dtofield (field_name, element, value, format);

     sm_i_dtofield (field_name, occurrence, value, format);

     sm_n_dtofield (field_name, value, format);

     sm_o_dtofield (field_number,occurrence, value, format);

     sm_dblval (field_number)

     sm_amt_format (field_number, text);

 

EXAMPLE

 

/* Place the value of pi on the screen, using the formatting

 * attached to the field. */

 

sm_n_dtofield ("pi", 3.141596, (char *)0);

 

/* Do it again, using only three decimal places.

 

sm_n_dtofield ("pi", 3.141596, "%5.3f");


 

NAME

 

 

     sm_dw_options - turn delayed write on or off

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_dw_options (flag)

     int flag;

 

DESCRIPTION

 

This function turns the delayed-write feature of the JAM library on or off. It

is on by default. The value of flag should be either DW_ON or DW_OFF.

 

When delayed write is on, output from library functions is not sent immediately

to the display, but is used to update a screen image in memory. When it becomes

necessary to update the display (usually when the keyboard is opened), output is

sent to the display a line at a time, and a check is made for keyboard input

between each line. If you press a key before the screen has been fully updated,

JAM processes the key before doing any more output. This scheme make JAM more

responsive, especially at low baud rates.

 

You may find it advantageous to turn delayed write off while debugging an

application, so that you can see the output produced by each function call. In

this case you should also investigate the BUFSIZ video file entry, which

controls the output buffer size; see the video manual in the Configuration

Guide. When delayed write is off, the display will still not be flushed until

the keyboard is opened; however, JAM will not check for input while writing to

the display.

 

If you define the SMDWOPTIONS variable in your setup file, it will cause this

function to be called automatically during start-up with the parameter you

specify there.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_getkey ();

     sm_ungetkey (key);

     sm_flush ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Turn delayed write off for debugging. */

 

#ifdef DEBUG

sm_dw_options (DW_OFF);

#endif

 

 

newpage NAME


 

     sm_e_1protect       selectively protect an array element sm_e_1unprotect

                         selectively unprotect an array element sm_e_amt_format

                         format data and write to an array element sm_e_bitop

                         manipulate field edit bits sm_e_chg_attr

                         change display attribute of an array element

                         sm_e_dblval

                         get decimal value of array element sm_e_dlength

                         get length of data stored in an array element

                         sm_e_dtofield

                         write decimal value to array element sm_e_fldno

                         * see next page * sm_e_fptr

                         get copy of array element's data sm_e_fval

                         force validation of an array element sm_e_getfield

                         copy data from array element into buffer sm_e_gofield

                         position cursor to an array element sm_e_intval

                         get integer value of data in an array element

                         sm_e_is_yes

                         test array element for yes sm_e_itofield

                         write integer to an array element sm_e_lngval

                         get long integer value of data in an array element

                         sm_e_ltofield

                         write long integer to an array element sm_e_mdt_clear

                         reset the MDT bit of an array element sm_e_mod_test

                         test the MDT bit of an array element sm_e_novalbit

                         reset the validated bit of an array element

                         sm_e_off_gofield

                         move cursor to specified offset within an array element

                         sm_e_protect

                         protect an array element from data entry sm_e_putfield

                         write data string to an array element sm_e_unprotect

                         allow data entry into an array element

 

DESCRIPTION

 

Each of the above functions accesses one element of an array by field name and

element number. For the description of sm_e_fldno, see next page. For a

description of any other particular function, look under the related function

without e_ in its name. For example, sm_e_amt_format is described under

sm_amt_format.

 

Despite the fact that they take a field name as argument, these functions do not

search the LDB for names not found in the screen.


 

NAME

 

     sm_e_fldno - get the field number of an array element

 

SYNOPSIS

 

     int sm_e_fldno (field_name, element)

     char *field_name;

     int element;

 

DESCRIPTION

 

Returns the field number of an array element specified by field_name and

element.

 

If element is zero, returns the field number of the named field, or of the base

element of the named array.

 

RETURNS

 

     0 if the name is not found, if the element number exceeds 1 and the named

          field is not an array, or if the element number exceeds the size of

          the array. Otherwise, returns an integer between 1 and the maximum

          number of fields on the current form.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_fldno (field_name);

 

EXAMPLE

 

/* Retrieve the field numbers of the first three elements of the

* "horses" array. */

 

int winnum, placenum, shownum;

 

winnum = sm_e_fldno ("horses", 1);

placenum = sm_e_fldno ("horses", 2);

shownum = sm_e_fldno ("horses", 3);


 

NAME

 

     sm_edit_ptr - get special edit string

 

SYNOPSIS

 

     #include "smdefs.h"

     char *sm_edit_ptr (field_number, command)

     int field_number, command;

 

DESCRIPTION

 

This function searches the special edits area of a field or array for an edit of

type command. The command should be one of the following values, which are

defined in smdefs.h :

     Command          Contents of edit string

 

     NAMED     Field name RANGEL

               Low bound on range; up to 9 permitted RANGEH

               High bound on range; up to 9 permitted NEXTFLD

               Next field (contains both primary and

               alternate fields) DOLLARS

               Amount field formatting parameters TEXT

               Status line prompt CPROG

               Name of field exit function HELPSCR

               Name of help screen CALC

               Math expression executed at field exit DATEFLD

               Format string for system-supplied date TIMEFLD

               Format string for system-supplied time CKDIGIT

               Flag and parameters for check digit FTYPE

               Data type for inclusion in structure USRDATE

               Format string for user-supplied date USRTIME

               Format string for user-supplied time ITEMSCR

               Name of item selection screen HARDHLP

               Name of automatic help screen HARDITM

               Name of automatic item selection screen MEMO1

               Nine arbitrary user-supplied text strings ...

               ... MEMO9

               ... FE_CPROG

               Name of field entry function EDT_BITS

               For internal use: bit string showing what

               other edits are present. Always first. RETCODE

               Return value for menu or return entry field JPLTEXT

               Attached JPL code, or JPL file name SUBMENU

               Name of pull-down menu screen CMASK

               Regular expression for field validation CCMASK

               Regular expression for character validation TABLOOK

               Name of screen for table-lookup validation

 

 

The string returned by this function has the command code in its second byte,

and the total length of the string (including the two overhead bytes and any

terminators) in its first; the body of the edit follows. If the field has no

edit of type command, this function returns a null string. If a field has

multiple edits of one type, such as RANGEH or RANGEL, the first one is returned;

the rest follow it.

 

This function is especially useful for retrieving user-defined information

contained in MEMO edits.


 

RETURNS

 

     A pointer to the first (length) byte of the special edit for this field is

          returned. Zero is returned if the field or edit is not found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_edit_ptr (field_name, command);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Useful little function to retrieve the name of a field. */

 

char *field_name (fieldnum)

int fieldnum;

{

     char *name;

 

     if (fieldnum < 1 || fieldnum > sm_numflds)

          return 0;

 

     if ((name = sm_edit_ptr (fieldnum, NAMED)) == 0)

          return 0;

     return name + 2;

}


 

NAME

 

     sm_emsg - display an error message and reset the message line, without

               turning on the cursor

 

SYNOPSIS

 

     void sm_emsg (message)

     char *message;

 

DESCRIPTION

 

This function displays message on the status line, if it fits, or in a window if

it is too long; it remains visible until the operator presses a key. The

function's exact behavior in dismissing the message is subject to the error

message options; see sm_er_options.

 

sm_emsg is identical to sm_err_reset, except that it does not attempt to turn

the cursor on before displaying the message.  It is similar to sm_qui_msg, which

inserts a constant string (normally "ERROR:") before the message. That string

may be altered by changing the SM_ERROR entry in the message file.

 

Several percent escapes provide control over the content and presentation of

status messages. They are interpreted by sm_d_msg_line, which is eventually

called by everything that puts text on the status line (including field status

text). The character following the percent sign must be in upper-case; this is

to avoid conflict with the percent escapes used by printf and its variants.

Certain percent escapes (%W, for instance; see below) must appear at the

beginning of the message, i.e. before anything except perhaps another percent

escape.

 

   .

      If a string of the form %Annnn appears anywhere in the message, the

      hexadecimal number nnnn is interpreted as a display attribute to be

      applied to the remainder of the message. The table below gives the

      numeric values of the logical display attributes you will need to

      construct embedded attributes. If you want a digit to appear

      immediately after the attribute change, pad the attribute to 4 digits

      with leading zeroes; if the following character is not a legal hex

      digit, leading zeroes are unnecessary.

   .

      If a string of the form %KKEYNAME appears anywhere in the message,

      KEYNAME is interpreted as a logical key mnemonic, and the whole

      expression is replaced with the key label string defined for that key

      in the key translation file. If there is no label, the %K is stripped

      out and the mnemonic remains. Key mnemonics are defined in smkeys.h ;

      it is of course the name, not the number, that you want here. The

      mnemonic must be in upper-case.

   .

      If %N appears anywhere in the message, the latter will be presented in

      a pop-up window rather than on the status line, and all occurrences of

      %N will be replaced by newlines.

   .

      If the message begins with a %B, JAM will beep the terminal (using

      sm_bel) before issuing the message.

   .

      If the message begins with %W, it will be presented in a pop-up window

      instead of on the status line. The window will appear near the bottom

      center of the screen, unless it would obscure the current field by so

      doing; in that case, it will appear near the top.  If the message

      begins with %MU or %MD, and is passed to one of the error message

      display functions, JAM will ignore the default error message

      acknowledgement flag and process (for %MU) or discard (for %MD) the

      next character typed.

Note that, if a message containing percent escapes - that is, %A, %B, %K, %N or

%W - is displayed before sm_initcrt or after %W is called, the percent escapes

will show up in it.

 

            Attribute               Hex value

 

          BLACK               0 BLUE

                              1 GREEN

                              2 CYAN

                              3 RED

                              4 MAGENTA

                              5 YELLOW

                              6 WHITE

                              7

 

          B_BLACK             0 B_BLUE

                              100 B_GREEN

                              200 B_CYAN

                              300 B_RED

                              400 B_MAGENTA

                              500 B_YELLOW

                              600 B_WHITE

                              700

 

          BLANK               8 REVERSE

                              10 UNDERLN

                              20 BLINK

                              40 HILIGHT

                              80 DIM

                              1000

 

If the cursor position display has been turned on (see sm_c_vis), the end of the

status line will contain the cursor's current row and column. If the message

text would overlap that area of the status line, it will be displayed in a

window instead.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_er_options (key, discard);

     sm_err_reset (message);

     sm_quiet_err (message);

     sm_qui_msg (message);

 

EXAMPLE

 

sm_emsg ("%MDYou goofed. Press %A0017any%A7 key to continue";


 

NAME

 

     sm_er_options - set error message options

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_er_options (acknowledge_key, flags)

     int acknowledge_key;

     int flags;

 

DESCRIPTION

 

This function affects the behavior of the error message display functions:

sm_err_reset, sm_emsg, sm_quiet_err, and sm_qui_msg. By default, an error

message remains on the display until you acknowledge it by pressing the space

bar; this function changes both the key and the requirements for error

acknowledgement.

 

Flags specifies whether the acknowledgement key is to be discarded, and (if so)

whether the hit-space window is to be displayed. The following two pairs of

flags are recognized:

 

   ER_DISCARD        Default. All error messages must be acknowledged by the

                     acknowledge_key, which is then discarded. Any other key

                     struck before the acknowledgement key will also be

                     discarded.

   ER_USE_KEY        Error messages may be acknowledged by any key, which is

                     then treated as ordinary keyboard input; for instance,

                     an invalid input message would be acknowledged by the

                     first character of the corrected input. However, the

                     keyboard typeahead buffer is flushed, so that anything

                     you typed before the message was displayed is still

                     discarded.

   ER_YES_WIND       Default. If ER_DISCARD is in effect and another key is

                     hit when the acknowledgement key is expected, a reminder

                     window pops up. (The text in the  window is obtained

                     from the message file entries SM_SP1 and SM_SP2.) Both

                     the reminder window and the message disappear when the

                     acknowledgement key is struck.

   ER_NO_WIND        If ER_DISCARD is in effect and another key is hit when

                     the acknowledgement key is expected, the terminal beeps.

 

If neither of one pair is specified, the corresponding option remains unchanged.

These options will be overridden by a %MD or %MU string at the beginning of a

message.

 

If you define the SMEROPTIONS variable in your setup file, it will cause this

function to be called automatically during start-up with the parameters you

specify there.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_emsg (message);

     sm_err_reset (message);

     sm_quiet_err (message);

     sm_qui_msg (message);


 

EXAMPLE

 

#include "smdefs.h"

 

/* Reset error message options to their defaults. */

 

sm_er_options (" ", ER_DISCARD|ER_YES_WIND);


 

NAME

 

     sm_err_reset - display an error message and reset the status line

 

SYNOPSIS

 

     void sm_err_reset (message)

     char *message;

 

DESCRIPTION

 

The message is displayed on the status line until you acknowledge it by pressing

a key. If message is too long to fit on the status line, it is displayed in a

window instead. The exact behavior of error message acknowledgement is governed

by sm_er_options. The initial message attribute is set by sm_ch_emsgatt, and

defaults to blinking.

 

This function turns the cursor on before displaying the message, and forces off

the global flag sm_do_not_display. It is similar to sm_emsg, which does not turn

on the cursor, and to sm_quiet_err, which inserts a constant string (normally

"ERROR:") before the message.

 

Several percent escapes provide control over the content and presentation of

status messages. They are interpreted by sm_d_msg_line, which is eventually

called by everything that puts text on the status line (including field status

text). The character following the percent sign must be in upper-case; this is

to avoid conflict with the percent escapes used by printf and its variants.

Certain percent escapes (%W, for instance; see below) must appear at the

beginning of the message, i.e. before anything except perhaps another percent

escape.

 

   .

      If a string of the form %Annnn appears anywhere in the message, the

      hexadecimal number nnnn is interpreted as a display attribute to be

      applied to the remainder of the message. The table below gives the

      numeric values of the logical display attributes you will need to

      construct embedded attributes. If you want a digit to appear

      immediately after the attribute change, pad the attribute to 4 digits

      with leading zeroes; if the following character is not a legal hex

      digit, leading zeroes are unnecessary.

   .

      If a string of the form %KKEYNAME appears anywhere in the message,

      KEYNAME is interpreted as a logical key mnemonic, and the whole

      expression is replaced with the key label string defined for that key

      in the key translation file. If there is no label, the %K is stripped

      out and the mnemonic remains. Key mnemonics are defined in smkeys.h ;

      it is of course the name, not the number, that you want here. The

      mnemonic must be in upper-case.

   .

      If %N appears anywhere in the message, the latter will be presented in

      a pop-up window rather than on the status line, and all occurrences of

      %N will be replaced by newlines.

   .

      If the message begins with a %B, JAM will beep the terminal (using

      sm_bel) before issuing the message.

   .

      If the message begins with %W, it will be presented in a pop-up window

      instead of on the status line. The window will appear near the bottom

      center of the screen, unless it would obscure the current field by so

      doing; in that case, it will appear near the top.  If the message

      begins with %MU or %MD, and is passed to one of the error message

      display functions, JAM will ignore the default error message

      acknowledgement flag and process (for %MU) or discard (for %MD) the

      next character typed.

Note that, if a message containing percent escapes - that is, %A, %B, %K, %N or

%W - is displayed before sm_initcrt or after %W is called, the percent escapes

will show up in it.

 

            Attribute               Hex value

 

          BLACK               0 BLUE

                              1 GREEN

                              2 CYAN

                              3 RED

                              4 MAGENTA

                              5 YELLOW

                              6 WHITE

                              7

 

          B_BLACK             0 B_BLUE

                              100 B_GREEN

                              200 B_CYAN

                              300 B_RED

                              400 B_MAGENTA

                              500 B_YELLOW

                              600 B_WHITE

                              700

 

          BLANK               8 REVERSE

                              10 UNDERLN

                              20 BLINK

                              40 HILIGHT

                              80 DIM

                              1000

 

If the cursor position display has been turned on (see sm_c_vis), the end of the

status line will contain the cursor's current row and column. If the message

text would overlap that area of the status line, it will be displayed in a

window instead.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_er_options (key, discard);

     sm_emsg (message);

     sm_quiet_err (message);

     sm_qui_msg (message);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Let somebody know that his name isn't in the database. */

 

int validate (field, name, occur, bits)

char *name;

{

     char buf[128];

 

     if (getrec (name) == 0)

     {

          sprintf (buf, "%s is not in the database.", name);

          sm_err_reset (buf);

          return -1;

     }

 

     return 0;

}


 

NAME

 

 

     sm_fcase - set case sensitivity when searching for screens

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_fcase (case)

     int case;

 

DESCRIPTION

 

Controls whether the matching of screen names in the form stack, form libraries,

and memory resident form list is case-sensitive. Case must be either CASE_SENS

or CASE_INSENS; those values are defined in smdefs.h . Refer to sm_r_window and

Section 12.1 for descriptions of the searches affected by this function.

 

RETURNS

 

     -1 if case was invalid ; 0 otherwise.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Use case-insensitive search on case-insensitive

 * operating systems. */

 

#if (defined MSDOS || defined VMS)

     sm_fcase (CASE_INSENS);

#endif


 

NAME

 

 

     sm_fextension - set default screen file extension

 

SYNOPSIS

 

     int sm_fextension (extension)

     char *extension;

 

DESCRIPTION

 

This function makes extension the default file extension for screen files. When

searching for a screen, JAM will append it to any name that does not already

contain an extension. Refer to sm_r_window and Section 12.1 for a description of

the searches affected by this function, and to the introduction to the

Configuration Guide for details on how JAM handles file extensions generally.

 

Extension should not contain any separator, such as a period. That and the

placement of the extension are controlled by the SMUSEEXT setup variable; by

default, extensions are placed at the end of the filename and are separated from

it by a period.

 

The same effect may be achieved by defining the SMFEXTENSION variable in your

setup file. Refer to the section on setup files in the Configuration Guide.

 

RETURNS

 

     -1 if insufficient memory is available to store the extension; 0 otherwise.

 

EXAMPLE

 

/* Change the default extension to "form". */

 

sm_fextension ("form");

 

/* Declare that screen files should have no default extension. */

 

sm_fextension ("");


 

NAME

 

     sm_flush - flush delayed writes to the display

 

SYNOPSIS

 

     void sm_flush ();

 

DESCRIPTION

 

This function performs delayed writes and flushes all buffered output to the

display. It is called automatically whenever the keyboard is opened and there

are no keystrokes available, i.e. typed ahead.

 

Calling this routine indiscriminately can significantly slow execution. As it is

called whenever the keyboard is opened, the display is always guaranteed to be

in sync before data entry occurs; however, if you want timed output or other

non-interactive display, use of this routine will be necessary.

 

sm_flush does two sorts of flushing: first it does output that has been delayed,

then it calls a system-dependent routine that empties display output buffers.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_rescreen ();

 

EXAMPLE

 

/* Update a system time field once per second, until a key

 * is pressed. */

 

while (!sm_keyhit (10))

{

     sm_n_putfield ("time_now", "");

     sm_flush ();

}

 

/* ...process the key */


 

NAME

 

     sm_formlist - update list of memory-resident forms

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_formlist (ptr_to_form_list)

     struct form_list *ptr_to_form_list;

 

DESCRIPTION

 

This function adds to a list of memory-resident forms. Each member of the list

is a structure giving the name of the form, as a character string, and its

address in memory.

 

The library functions sm_r_form, sm_r_window, and sm_r_at_cur, which are all

called with a screen name as parameter, search for it in the memory-resident

form list before attempting to read the screen from disk.

 

This function is called once from sm_initcrt to pick up the global list

sm_memforms; this is for compatibility with Release 3. It can be called any

number of times from an application program to add forms to the list.

 

Since no count is given with the list, care must be taken to end the new list

with a null entry.

 

RETURNS

 

     -1 if insufficient memory is available for the new list; 0 otherwise.

 

EXAMPLE

 

#include "smdefs.h"

 

/* The following code adds two screens to the

 * memory-resident form list. */

 

struct form_list new_list[] =

{

     "new_form1",  new_form1,

     "new_form2",  new_form2,

     "",        0

};

 

sm_formlist (new_list);


 

NAME

 

 

     sm_fptr - get the contents of a field

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_fptr (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the contents of the field specified by field_number. Leading blanks in

right-justified fields, and trailing blanks in left-justified fields, are

stripped.

 

This function shares with several others a pool of buffers where it stores

returned data. The value returned by any of them should therefore be processed

quickly or copied. sm_getfield is not subject to this restriction.

 

RETURNS

 

     The field contents, or 0 if the field cannot be found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_fptr (field_name, element);

     sm_i_fptr (field_name, occurrence);

     sm_n_fptr (field_name);

     sm_o_fptr (field_number, occurrence);

     sm_getfield (buffer, field_number);

     sm_putfield (field_number, text);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Little function to tell somebody something s/he

 * already knows. */

 

void report (fieldname)

char *fieldname;

{

     char buf[256], *stuf;

     if ((stuf = sm_n_fptr (fieldname)) == 0)

          return;

 

     sprintf (buf, "You have typed %s in the %s field.",

          stuf, fieldname);

     sm_emsg (buf);

}


 

NAME

 

     sm_fval - force field validation

 

SYNOPSIS

 

     int sm_fval (field_number)

     int field_number;

 

DESCRIPTION

 

This function performs all validations on the indicated field or occurrence, and

returns the result. If the field is protected against validation, the checks are

not performed and the function returns 0; see sm_1protect. Validations are done

in the order listed below. Some will be skipped if the field is empty, or if its

VALIDED bit is already set (implying that it has already passed validation).

 

              Validation         Skip if valid       Skip if empty

 

        required           y            n

        must fill          y            y

        regular expression y            y

        range              y            y

        check-digit        y            y

        date or time       y            y

        table lookup       y            y

        currency format    y            n*

        math expresssion   n            n

        exit function      n            n

        jpl function       n            n

 

*

 The currency format edit contains a skip-if-empty flag; see the Author's Guide.

 

If you need to force a skip-if-empty validation, make the field required. A

digits-only field must contain at least one digit in order to be considered

nonempty; for other character edits, any nonblank character makes the field

nonempty.

 

Math expressions and field exit functions are never skipped, since they can

alter fields other than the one being validated. If you are planning to use this

function, be careful to make no assumptions about the cursor position when

writing field exit functions. Often it is assumed that the cursor is in the

field being validated, so that sm_tab and similar functions will work properly.

 

Field validation is performed automatically within sm_openkeybd when the cursor

exits a field. Application programs need call this function only to force

validation of other fields.

 

RETURNS

 

     -2 if the field or occurrence specification is invalid; -1 if the field

          fails any validation; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_fval (array_name, element);

     sm_i_fval (field_name, occurrence);

     sm_n_fval (field_name);

     sm_o_fval (field_number, occurrence);

     sm_s_val ();


 

EXAMPLE

 

#include "smdefs.h"

 

/* Make sure that the previous field has been validated

* before checking the current one. */

 

validate (fieldnum, data, occurrence, bits)

char *data;

{

     if (sm_fval (fieldnum - 1))

     {

          /* Place cursor in the previous field and indicate error */

          sm_gofield (fieldnum - 1);

          return 1;

     }

     ...

}


 

NAME

 

     sm_getcurno - get current field number

 

SYNOPSIS

 

     int sm_getcurno ();

 

DESCRIPTION

 

Returns the number of the field in which the cursor is currently positioned. The

field number ranges from 1 to the total number of fields in the screen.

 

RETURNS

 

     Number of the current field, or 0 if the cursor is not within a field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_occur_no ();

 

EXAMPLE

 

/* Imagine that the screen contains an 8 by 8 array

 * of fields, like a checkerboard. The following code

 * gets the number of the current field and returns

 * the corresponding row and column. */

 

void get_location (row, column)

int *row, *column;

{

     int fieldnum;

 

     if ((fieldnum = sm_getcurno ()) == 0)

          *row = *column = -1;

     else

     {

          *row = (fieldnum - 1) / 8 + 1;

          *column = (fieldnum - 1) % 8 + 1;

     }

}


 

NAME

 

     sm_getfield - copy the contents of a field

 

SYNOPSIS

 

     int sm_getfield (buffer, field_number)

     char *buffer;

     int field_number;

 

DESCRIPTION

 

Copies the data found in field_number to buffer.  Leading blanks in

right-justified fields, and trailing blanks in left-justified fields, are not

copied.

 

Responsibility for providing a buffer large enough for the field's contents

rests with the calling program. This should be at least one greater than the

maximum length of the field, taking shifting into account.

 

Note that the order of arguments to this function is different from that to the

related function sm_putfield.

 

RETURNS

 

     The total length of the field's contents, or -1 if the field cannot be

          found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_getfield (buffer, field_name, element);

     sm_i_getfield (buffer, field_name, occurrence);

     sm_n_getfield (buffer, field_name);

     sm_o_getfield (buffer, field_number, occurrence);

     sm_fptr (field_number);

     sm_putfield (field_number, text);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Save the contents of the "rank" field in a buffer

 * of the proper size. */

 

int size;

char *save_rank;

 

size = sm_n_length ("rank");

if ((save_rank = malloc (size + 1)) == 0)

     punt ("Malloc error");

 

if (sm_n_getfield (save_rank, "rank") > size)

     punt ("Bug in sm_length or sm_getfield!");


 

NAME

 

     sm_getkey - get translated value of the key hit

 

SYNOPSIS

 

     #include "smkeys.h"

 

     int sm_getkey ();

 

DESCRIPTION

 

Gets and interprets keyboard input according to an algorithm described

elsewhere, and returns the interpreted value to the calling program. Normal

characters are returned unchanged; function keys are interpreted according to a

key translation file for the particular computer or terminal you are using.

 

Function keys include TRANSMIT, EXIT, HELP, LOCAL PRINT, arrows, data

modification keys like INSERT and DELETE CHAR, user function keys PF1 through

PF24, shifted function keys SPF1 through SPF24, and others. Defined values for

all are in smkeys.h . A few function keys, such as LOCAL PRINT and RESCREEN, are

processed locally in sm_getkey and not returned to the caller.

 

There is another function called sm_ungetkey, which pushes logical key values

back on the input stream for retrieval by sm_getkey. Since all JAM input

routines call sm_getkey, you can use it to generate any input sequence

automatically. When you use it, calls to sm_getkey will not cause the display to

be flushed, as they do when keys are read from the keyboard.

 

There is a key-change hook in sm_getkey. Before returning a translated key to

its caller, it passes the key to a user-installed function which may alter the

key value, delete it from the input stream, or whatever. See sm_u_keychange and

sm_install.

 

There is another pair of hooks, for recording and playing back sequences of

keys. These are a recording function, which is passed the key just typed, and a

playback function, which is called to obtain a key. See sm_u_record and

sm_u_play.

 

Finally, there is a mechanism for detecting an externally established abort

condition, essentially a flag, which causes JAM input functions to return to

their callers immediately. The present function checks for that condition on

each iteration, and returns the ABORT key if it is true. See sm_isabort.

 

Application programmers should be aware that JAM control strings are not

executed within this function, but at a higher level within the JAM run-time

system. If you call this function, do not expect function key control strings to

work.

 

 

RETURNS

 

     The standard ASCII value of a displayable key; a value greater than 255 (FF

          hex) for a key sequence in the key translation file.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_ungetkey (key);

     sm_u_keychange (key);

     sm_keyfilter (flag);

     sm_u_play ();

     sm_u_record (key);

     sm_isabort (flag);


 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Alternate version of sm_query_msg, which makes up

 * its mind right away. */

 

int query (text)

char *text;

{

     int key;

 

     sm_d_msg_line (text, REVERSE);

     for (;;)

     {

          switch (key = sm_getkey ())

          {

          case XMIT:

          case 'y':

          case 'Y':

               sm_d_msg_line ("", WHITE");

               return 1;

          default:

               sm_emsg ("%MU I take that for a 'no'");

               sm_d_msg_line ("", WHITE");

               return 0;

          }

     }

}


 

PSEUDOCODE

 

The multiplicity of hooks in sm_getkey makes it a little difficult to see how

they interact, which take precedence, and so forth. In an effort to clarify the

process, we present an outline of sm_getkey. The process of key translation is

deliberately omitted, for the sake of clarity; that algorithm is presented

separately, toward the end of this chapter.

 

-- Step 1

 

If an abort condition exists,

     return the ABORT key.

 

If there is a key pushed back by ungetkey,

     return that.

 

If playback is active and a key is available,

     take it directly to Step 2; otherwise read and translate input from the

     keyboard.

 

 

-- Step 2

 

Pass the key to the keychange function. If that function says to discard the

key, go back to Step 1; otherwise if an abort condition exists,

     return the ABORT key.

 

If recording is active,

     pass the key to the recording function.

 

 

-- Step 3

 

If the routing table says the key is to be processed locally,

     do so.

 

If the routing table says to return the key,

     return it; otherwise, go back to Step 1.


 

NAME

 

     sm_gofield - move the cursor into a field

 

SYNOPSIS

 

     int sm_gofield (field_number)

     int field_number;

 

DESCRIPTION

 

Positions the cursor to the first enterable position of field_number. If the

field is shiftable, it is reset.

 

In a right-justified field, the cursor is placed in the rightmost position; in a

left-justified field, in the leftmost. In either case, if the field is

digits-only, the cursor goes to the nearest position not occupied by a

punctuation character. Use sm_off_gofield to place the cursor elsewhere than in

the first position.

 

When called to position the cursor in a scrollable field or array, sm_o_gofield

and sm_i_gofield return an error if the occurrence number passed exceeds by more

than 1 the number of items in the specified field or array.

 

RETURNS

 

     -1 if the field is not found; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_gofield (field_name, element)

     sm_i_gofield (field_name, occurrence)

     sm_n_gofield (field_name)

     sm_o_gofield (field_number, occurrence)

     sm_getcurno ();

     sm_off_gofield (field_number, offset);

 

EXAMPLE

 

#include "smdefs.h"

 

/* If the combination of this field and the previous one

 * is invalid, go back to the previous for data entry. */

 

int validate (field, data, occur, bits)

char *data;

{

     if (bits & VALIDED)

          return 0;

 

     if (!lookup (data, sm_fptr (field - 1)))

     {

          sm_novalbit (field - 1);

          sm_gofield (field - 1);

          sm_quiet_err ("Lookup failed - please re-enter both items.");

          return 1;

     }

     return 0;

}


 

NAME

 

     sm_hlp_by_name - present help window

 

SYNOPSIS

 

     int sm_hlp_by_name (help_screen)

     char *help_screen;

 

DESCRIPTION

 

The named screen is displayed and processed as a normal help screen, including

input processing for the current field (if any). Four types of help screens are

automatically recognized and processed:

 

  1.  A help screen with one unprotected field, which has no attached

      function. This function will change the help field's length to that of

      the underlying field, if necessary by making the help field shiftable;

      and it will copy the underlying field's contents and most of its edits

      into the help field.  The operator may then change the help field's

      contents, and, by hitting TRANSMIT, have the new contents copied back

      to the underlying field.

  2.  A help screen with two or more unprotected fields, all of which are

      menu fields.  The screen will be treated as a menu, except that menu

      entries will be used only to bring up lower level help screens.

  3.  A help screen with entry-protected fields only.  The screen is

      displayed until the operator hits either EXIT or TRANSMIT. Hitting the

      HELP key while the cursor is in a field will bring up any help screen

      associated with that field.

  4.  A help screen with display data only.  The screen is displayed until

      the operator hits any returnable key (excluding such keys as LOCAL

      PRINT, RESCREEN, or HELP), at which point the window is closed.

 

Refer to the Author's Guide for further instructions on how to create each kind

of help screen.

 

RETURNS

 

     -1 if screen is not found or other error; 1 if data copied from help screen

          to underlying field; 0 otherwise.

 

EXAMPLE

 

#include "smdefs.h"

 

/* If user tabs out of empty field, find the field's

 * help screen and execute it. Implemented as a validation

 * function. */

 

nonempty (field, data, occur, bits)

char *data;

{

     char *helpscreen;

 

     if (*data == 0)

     {

          if ((helpscreen = sm_edit_ptr (field, HELP)) != 0 ||

               (helpscreen = sm_edit_ptr (field, HARDHELP)) != 0)

               sm_hlp_by_name (helpscreen + 2);

     }

 

     return 0;

}


 

NAME

 

     sm_home - home the cursor

 

SYNOPSIS

 

     int sm_home ();

 

DESCRIPTION

 

This routine moves the cursor to the first enterable position of the first

tab-unprotected field on the screen; or, if the form has no tab-unprotected

fields, to the first line and column of the topmost window.

 

The cursor will be put into a tab-protected field if it occupies the first line

and column of the window and there are no tab-unprotected fields.

 

RETURNS

 

     The number of field in which the cursor is left, or 0 if the form has no

          unprotected fields and the home position is not in a protected field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_gofield (field_number);

     sm_last ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Suppose that at some point the data entry process

 * has gotten fouled up beyond all repair. The following

 * code fragment could be used to start it over. */

 

/* ... */

sm_cl_unprot ();

sm_home ();

sm_err_reset ("%MUI'm confused! Let's start over.");

/* ... */


 

NAME

 

     sm_i_achg           change the display attribute of a scrolling item

                         sm_i_amt_format

                         format data and write to occurrence sm_i_bitop

                         manipulate edit bits of an occurrence sm_i_dblval

                         get decimal value of occurrence sm_i_dlength

                         get length of data in occurrence sm_i_doccur

                         delete an occurrence sm_i_dtofield

                         write decimal value to occurrence sm_i_fptr

                         get copy of occurrence's data sm_i_fval

                         force validation of occurrence sm_i_getfield

                         copy data from occurrence into buffer sm_i_gofield

                         position cursor to occurrence sm_i_intval

                         get integer value of occurrence sm_i_ioccur

                         insert a blank occurrence into a scroll or array

                         sm_i_itofield

                         write integer to occurrence sm_i_lngval

                         get long integer value of occurrence sm_i_ltofield

                         write long integer to occurrence sm_i_mdt_clear

                         reset MDT bit of an occurrence sm_i_mod_test

                         test MDT bit of an occurrence sm_i_novalbit

                         reset validated bit of an occurrence sm_i_off_gofield

                         place cursor in the middle of an occurrence

                         sm_i_putfield

                         write data string to occurrence

 

DESCRIPTION

 

Each of the above functions refers to data by field name and occurrence number.

As used in the above functions, occurrence means

 

  1.  item, if the field or array is scrollable;

  2.  element, if the specified field is part of a non-scrollable array; or

  3.  the specified field, if neither scrollable nor an array.

 

If occurrence is zero, the reference is always to the current contents of the

named field, or of the base field of the named array.

 

For the description of a particular function, look under the related function

without i_ in its name. For example, sm_i_amt_format is described under

sm_amt_format.

 

If the named field is not on the screen, these functions will attempt to

retrieve or change its value in the local data block.


 

NAME

 

     sm_inbusiness - tell whether the screen manager is up and running or

                     not

 

SYNOPSIS

 

     int sm_inbusiness ();

 

DESCRIPTION

 

This function inspects internal screen manager flags and data structures to

determine whether screen manager I/O is in progress, and returns a nonzero value

if it is. The library functions sm_initcrt and sm_return turn on that state;

sm_resetcrt and sm_leave turn it off.

 

Applications may find this function useful in deciding how to display error

messages, or how to handle error conditions generally.

 

RETURNS

 

     1 if the screen manager is running, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_initcrt ();

     sm_resetcrt ();

     sm_leave ();

     sm_return ();

 

EXAMPLE

 

#define ERRMSG1 "Insufficient memory available"

char *buf;

 

if ((buf = malloc (4096)) == 0)

{

     if (sm_inbusiness ())

          sm_quiet_err (ERRMSG1);

     else fprintf (stderr, "%s\n", ERRMSG1);

}


 

NAME

 

 

     sm_ind_set - control onscreen shifting and scrolling indicators

 

SYNOPSIS

 

     int sm_ind_set (flag)

     int flag;

 

DESCRIPTION

 

This function controls the presence and style of shifting and scrolling

indicators, which JAM uses to indicate the presence of offscreen data in a field

or array. Flag is restricted to the following values, which are defined in

smdefs.h  . The where codes are to be ored with the whether codes:

 

                   Whether to display indicators

 

          IND_NONE       no indicators

          IND_SHIFT      shifting indicators only

          IND_SCROLL     scrolling indicators only

          IND_BOTH       shift and scroll

 

               Where to display scrolling indicators

 

          IND_FULL       full width of field

          IND_FLDLEFT    left corner of field

          IND_FLDCENTER  center of field

          IND_FLDRIGHT   right side of field

          IND_FLDENTRY   left or right, according to

                         the field's justification

 

 

If flag is IND_NONE, the existing indicators are erased from the display and the

indicator table is discarded; otherwise, an indicator table is allocated if

needed, and the new indicators are displayed. The default setting is IND_BOTH

and IND_FULL.

 

This function should be called before reading the screen for which indicators

are desired; normally, it is called once at the beginning of the program.

Closing a window does not perform a recalculation, but restores the underlying

screen's indicators; to avoid confusion, this function should be called when no

windows are displayed.

 

If you define the SMINDSET variable in your setup file, it will cause this

function to be called automatically during start-up with the parameters you

specify there.

 

RETURNS

 

     -1 if sufficient memory for a new table was not available; 0 otherwise.

 

EXAMPLE

 

#include "smdefs.h"

/* Set indicator display back to defaults */

sm_ind_set (IND_BOTH | IND_FULL);


 

NAME

 

     sm_ininames - record names of initial data files for local data block

 

SYNOPSIS

 

     int sm_ininames (name_list)

     char *name_list;

 

DESCRIPTION

 

Sets up a list of initialization files for local data block items. The file

names in the single string name_list should be separated by commas, semicolons

or blanks; there may be up to ten of them. The files themselves contain pairs of

names and values, which are used to initialize local data block items by

sm_ldb_init, q.v. That function is called automatically during JAM

initialization, so sm_ininames should be called before then. White space in the

initialization files is ignored, but we suggest a format like the following:

 

     "emperor"           "Julius Caesar" "lieutenant"

                         "Mark Antony" "assassin[1]"

                         "Brutus" "assassin[2]"

                         "Cassius"

 

You may achieve the same effect by defining the SMININAMES variable in your

setup file to the list of names. See the section on setup files in the

Configuration Guide for details.

 

Items of all scopes may be freely mixed within all files. We recommend, however,

that items be grouped in files by scope if you are planning to use sm_lreset,

q.v. That function clears all items of a given scope before reinitializing them

from a single file.

 

RETURNS

 

     -5 if insufficient memory is available to store the names; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_lreset (scope, filename);

     sm_ldb_init ();

 

EXAMPLE

 

/* Set up five initialization files. */

 

sm_ininames ("scope0.ini, scope1.ini, scope2.ini,\

scope3.ini, scope4.ini");


 

NAME

 

     sm_initcrt - initialize the display and JAM data structures

 

SYNOPSIS

 

     void sm_initcrt (path)

     char *path;

 

DESCRIPTION

 

This function must be called at the beginning of screen handling, that is,

before any screens are displayed or the keyboard opened for input to a JAM

screen. Functions that set options, such as sm_ok_options, and those that

install functions or configuration files, such as sm_install or sm_vinit, are

the only kind that may be called before sm_initcrt.

 

Path is a directory to be searched for screen files by sm_r_window and variants.

First the file is sought in the current directory; if it is not there, it is

sought in the path supplied to this function. If it is not there either, the

paths specified in the environment variable SMPATH (if any) are tried. The path

argument must be supplied. If all forms are in the current directory, or if (as

JYACC suggests) all the relevant paths are specified in SMPATH, an empty string

may be passed. After setting up the search path, sm_initcrt performs several

initializations:

 

  1.  It calls a user-defined initialization routine (see sm_u_uinit).

  2.  It determines the terminal type, if possible by examining the

      environment (TERM or SMTERM), otherwise by asking you.

  3.  It executes the setup files defined by the environment variables SMVAGS

      and SMSETUP, and reads in the binary configuration files (message, key,

      and video) specific to the terminal.

  4.  It allocates memory for a number of data structures shared among JAM

      library functions.

  5.  If supported by the operating system, keyboard interrupts are trapped

      to a routine that clears the screen and exits.

  6.  It initializes the operating system screen and keyboard channels, and

      clears the display.

 

This function is called automatically during JAM start-up, and should not be

called by application programs.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_smsetup ();

     sm_uinit (term_type);

     sm_msgread (prefix, range, address, name);

     sm_vinit (video_file);

     sm_keyinit (key_file);

 

EXAMPLE

 

/* To initialize the screen manager without supplying a path

* for screens: */

 

     sm_initcrt ("");


 

NAME

 

 

     sm_install - attach application functions to JAM library hooks

 

SYNOPSIS

 

     #include "smdefs.h"

 

     struct fnc_data *sm_install (which_hook,

          what_funcs, howmany)

     int which_hook;

     struct fnc_data what_funcs[];

     int *howmany;

 

DESCRIPTION

 

This function places an application routine on one of the screen manager library

hooks; this enables JAM to pass control to your code in the proper context. Each

hook is documented separately in this chapter; refer to the table below.

 

Which_hook must be drawn from the following list. It identifies the hook your

routine is to be attached to.

 

         Which            Purpose         Refer to

 

     UINIT_FUNC     initialization        sm_u_uinit

     URESET_FUNC    exit-time cleanup     sm_u_ureset

     VPROC_FUNC     video processing      sm_u_vproc

     CKDIGIT_FUNC   check digit computation

                    sm_u_ckdigit

     KEYCHG_FUNC    translated key peek/poke

                    sm_u_keychg

     INSCRSR_FUNC   insert/overwrite toggle

                    sm_u_inscrsr

     PLAY_FUNC      play back saved keys  sm_u_play

     RECORD_FUNC    record keys for playback

                    sm_u_record

     AVAIL_FUNC     check for recorded keys

                    sm_u_avail

     ASYNC_FUNC     asynchronous function sm_u_async

     STAT_FUNC      status line function  sm_u_statfnc

     ATTCH_FUNC     field attached function list

                    Section 1.3

     FORM_FUNC      screen entry/exit listSection 1.4

     CARET_FUNC     invoked function list Section 1.2

 

 

The last three hooks mentioned are not for single functions, but for lists of

functions. When you install these, names are required in the fnc_data

structures; what_funcs should be an array of structures; and howmany should hold

the number of functions in the list. Your functions are added to any already in

the list.

 

The second parameter, what_funcs, is the address of a structure describing an

application routine. If which_hook is a list, it is the address of an array of

such structures. Here is a definition of the structure:


 

struct fnc_data {

     char *fnc_name;

     int (*fnc_addr)();

     char language;

     char intrn_use;

     char appl_use;

     char reserved;

};

 

   .

      Fnc_name is a character string naming your routine. It is required only

      if which_hook is ATTCH_FUNC, CARET_FUNC, or FORM_FUNC, and should match

      the function name used in your screens.

   .

      Fnc_addr is always required. It is the address of your routine.

   .

      Language is a language identifier, drawn from smdefs.h . C is always 0.

   .

      Intrn_use serves as an installation parameter. Currently it is used

      with ASYNC_FUNC and the lists; see below.

   .

      Appl_use is reserved for your own use.

   .

      reserved is reserved for future use by JYACC.

 

The third parameter, howmany, is required only if which_hook is a list. It is

the address of an integer variable giving the number of entries in your list.

The count is passed by reference so that sm_install can return a count for the

new list with its return value. If the value pointed to by howmany is zero, all

functions in the list are removed, except those having a non-zero value in the

intrn_use field of the structure. Built-in functions supplied with JAM are

protected from removal in this fashion.

 

When you are installing an asynchronous function using ASYNC_FUNC, the intrn_use

field of the structure should be set to the timeout, in tenths of a second.

While the keyboard is idle, the asynchronous function will be called at that

interval.

 

RETURNS

 

     The address of the old function data structure(s), or zero if no function

          was previously installed. For lists of functions, also places the

          number of entries in the new list in howmany.


 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/************* Example 1 *************/

 

/* Here is a function to change the RETURN key to TAB, and

 * chain to the old keychange function, which is stored in

 * prev_fix.

 */

static struct fnc_data *prev_fix;

 

int keyfix (key)

{

     int k = key == NL ? TAB : key;

     if (prev_fix)

          return (*(prev_fix->fnc_addr)) (k);

     else return k;

}

 

/* Install the new function, storing the old one in prev_fix.

 * You must take the address of the fnc_data structure.

 */

 

static struct fnc_data fix = {

     0, keyfix, 0, 0, 0, 0

};

 

prev_fix = sm_install (KEYCHG_FUNC, &fix, (int *)0);

 

/************* Example 2 *************/

 

/* Install two attached functions, defined elsewhere.

 */

 

extern int atch1(), atch2();

 

static struct fnc_data atch[] = {

     { "atch1", atch1, 0, 0, 0, 0 },

     { "atch2", atch2, 0, 0, 0, 0 },

};

int count;

 

count = sizeof(atch) / sizeof(struct fnc_data);

sm_install (ATTCH_FUNC, atch, &count);


 

NAME

 

     sm_intval - get the integer value of a field

 

SYNOPSIS

 

     int sm_intval (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the integer value of the data contained in the field specified by

field_number. Any punctuation characters in the field (except, of course, a

leading plus or minus sign) are ignored.

 

RETURNS

 

     The integer value of the specified field, or zero if the field is not

          found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_intval (field_name, element);

     sm_i_intval (field_name, occurrence);

     sm_n_intval (field_name);

     sm_o_intval (field_number, occurrence);

     sm_itofield (field_number, value);

 

EXAMPLE

 

/* Retrieve the integer value of the "sequence" field. */

 

int sequence;

 

sequence = sm_n_intval ("sequence");


 

NAME

 

 

     sm_ioccur - insert blank occurrences

 

SYNOPSIS

 

     int sm_o_ioccur (field_number, occurrence, count)

     int field_number;

     int occurrence;

     int count;

 

DESCRIPTION

 

Inserts count blank data items before the specified occurrence, moving that

occurrence and all following occurrences down. If inserting that many would move

some occurrence past the end of its array or scrolling array, fewer will be

inserted. This function never increases the maximum number of items a scroll can

contain; sm_sc_max does that. If count is negative, occurrences will be deleted

instead, subject to limitations described in the page for sm_doccur.

 

If occurrence is zero, the occurrence used is that of field_number. If

occurrence is nonzero, however, it is taken relative to the first field of the

array in which field_number occurs.

 

This function is normally bound to the INSERT LINE key. It has only two

variants, sm_i_ioccur and sm_o_ioccur; the other three, including sm_ioccur

itself, do not exist.

 

RETURNS

 

     -1 if the field or occurrence number is out of range; -3 if insufficient

          memory is available; otherwise, the number of occurrences actually

          inserted (zero or more).

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_i_ioccur(field_name, occurrence, count);

     sm_i_doccur(field_name, occurrence, count);

     sm_o_doccur(field_number, occurrence, count);

 

EXAMPLE

 

#include "smkeys.h"

 

/* As a shortcut, make the PF5 key insert five blank

 * lines in the "amounts" array. */

 

int field, key;

 

while ((key = sm_openkeybd ()) != EXIT)

{

     if (key == PF5)

     {

          /* Make sure we're in the right place */

          field = sm_base_fldno (sm_getcurno ());

          if (field == sm_n_fldno ("amounts"))

               sm_o_ioccur (field, 0, 5);

     }

     ...

}


 

NAME

 

     sm_is_yes - boolean value of a yes/no field

 

SYNOPSIS

 

     int sm_is_yes (field_number)

     int field_number;

 

DESCRIPTION

 

The first character of the specified field_number is compared with the first

letter of the SM_YES entry in the message file, ignoring case, and the resulting

logical value is returned.

 

This function is ordinarily used with one-letter fields restricted to yes or no

by the appropriate character edit. Unlike the field data retrieval functions

(sm_fptr, etc.), it does not ignore leading blanks.

 

RETURNS

 

     1 if the field is found, and its contents match as described above; 0

          otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_is_yes (field_name);

     sm_e_is_yes (field_name, element);

     sm_i_is_yes (field_name, occurrence);

     sm_o_is_yes (field_number, occurrence);

 

EXAMPLE

 

/* Keep processing until the user enters "n" in

 * a flag field. This is an alternative for the

 *& usual checking against the EXIT key. */

 

while (sm_n_is_yes ("continue"))

{

     sm_openkeybd ();

}


 

NAME

 

     sm_isabort - test and set the abort control flag

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_isabort (flag)

     int flag;

 

DESCRIPTION

 

This function sets the abort flag to the value of flag, and returns the old

value. Flag must be one of the following:

 

          Flag           Meaning

 

          ABT_ON         set abort flag ABT_OFF

                         clear abort flag ABT_DISABLE

                         turn abort reporting off ABT_NOCHANGE

                         do not alter the flag

 

 

Abort reporting is intended to provide a quick way out of processing in the JAM

library, which may involve nested calls to sm_openkeybd and other input

functions. The triggering event is the detection of an abort condition by

sm_getkey, either an ABORT keystroke or a call to this function with ABT_ON.

 

This function enables application code to verify the existence of an abort

condition by testing the flag, as well as to establish one. You may need to

verify it because certain functions, such as sm_choice, cannot return the ABORT

key directly. Abort processing is described in detail later in this chapter.

 

RETURNS

 

     The previous value of the abort flag.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Establish an abort condition */

 

sm_isabort (ABT_ON);

 

/* Verify that an abort condition exists, without

 * altering it. */

 

if (sm_isabort (ABT_NOCHANGE) == ABT_ON)

     ...


 

NAME

 

     sm_itofield - write an integer value to a field

 

SYNOPSIS

 

     int sm_itofield (field_number, value)

     int field_number, value;

 

DESCRIPTION

 

The integer passed to this routine is converted to characters and placed in the

specified field. A number longer than the field will be truncated (on the left

or right, according to the field's justification) without warning.

 

RETURNS

 

     -1 if the field is not found; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_itofield (field_name, element, value);

     sm_i_itofield (field_name, occurrence, value);

     sm_n_itofield (field_name, value);

     sm_o_itofield (field_number, occurence, value);

     sm_intval (field_number);

 

EXAMPLE

 

/* Find the length of the data in field number 12, and

 * tell somebody about it. */

 

sm_n_itofield ("count", sm_dlength (12));


 

NAME

 

     sm_jclose - close current window under JAM control

 

SYNOPSIS

 

     int sm_jclose ();

 

} DESCRIPTION

 

The currently open window is erased, and the screen is restored to the state

before the window was opened. Since windows are stacked, the effect of closing a

window is to return to the previous window. The cursor reappears at the position

it had before the window was opened.

 

Note that this function closes a window regardless of whether it was opened via

a control string, or sm_jwindow. If the last window was opened through a call to

sm_r_window the results are unpredictable.

 

RETURNS

 

     -1 is returned if there is no window open, i.e. if the currently displayed

          screen is a form (or if there is no screen up). 0  is returned

          otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_jwindow (screen_arg);

 

EXAMPLE

 

/* This is an example of a caret function attached to the  XMIT */

/* key. It validates login and password information. If the  */

/* login and password are incorrect, the program proceeds to */

/* close three of the four "security" windows used for getting*/

/* a user's login and password information, and the user may */

/* again attempt to enter the information. If the password */

/* passes, the welcome screen is displayed, and the user may */

/* proceed.

 

int complete_login(jptr);

char *jptr;

{

     char pass[10];

     sm_n_getfield("pass", "password");

     if(!check_password(pass)) /*call routine to validate password*/

     {

          sm_jclose();      /*close current password window*/

          sm_jclose();      /*close 3rd underlying login window*/

          sm_jclose();      /*close 2nd underlying login window*/

          sm_emsg("Please reenter login and password");

     }                                       /*in bottom window*/

     else

     {

          sm_d_msg_line("Welcome to Security Systems, Inc.");

          sm_jform("Welcome");

                           /*open welcome screen*/

     }

     return (0);

}


 

NAME

 

     sm_jform - display a screen as a form under JAM control

 

SYNOPSIS

 

     int sm_jform (screen_name)

     char *screen_name;

 

DESCRIPTION

 

This function displays the named screen as a base form. The form's opening and

closing (with the EXIT key) are under JAM control. The function is similar to

sm_r_form.

 

Bringing up a screen as a form causes the previously displayed form and windows

to be discarded, and their memory freed. The new form is displayed with its

upper left-hand corner at the extreme upper left of the screen.

 

If the form contains display data that are too big for the physical display,

they are truncated without warning. However, if there are fields that won't fit

within the physical display, this function returns an error without displaying

the form.

 

The named form is sought on disk in the current directory; then under the path

supplied to sm_initcrt; then in all the paths in the setup variable SMPATH. If

any path exceeds 80 characters, it is skipped. If the entire search fails, this

function displays an error message and returns.

 

In the case of a return of -1, -2 or -7 the previously displayed form is still

displayed and may be used. Other negative return code indicate that the display

is undefined; the caller should display another form before using screen manager

functions. The return code -2 typically means that the named screen does not

exist; however, it may occur because the maximum allowable number of files is

already open.

 

RETURNS

 

     0 if no error occurred; -1 if the screen file's format is incorrect; -2 if

          the form cannot be found; -4 if, after the screen has been cleared,

          the form cannot be successfully displayed because of a read error; -5

          if, after the screen was cleared, the system ran out of memory; -7 if

          the screen was larger than the physical display, and there were fields

          that would have fallen outside the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_form (screen_name);

     sm_jwindow (name, line, column);


 

EXAMPLE

 

/* This exemplifies a caret function attached to the XMIT key. */

/* Here we have completed entering data on the second of several*/

/* security screens. If the user entered "bypass" into the login, */

/* he bypasses the other security screens, and the "welcome" */

/* screen is displayed. If the user login is incorrect, the */

/* current window is closed, and the user is back at the */

/* initial screen (below). Otherwise, the next security window */

/* is displayed. */

 

 

int getlogin(jptr)

char *jptr;

{

     char password[10];

     sm_n_getfield(password, "password");

     /* check if "bypass" has been entered into login */

     if (strcmp(password,"bypass"))

          sm_jform("welcome");

     /* check if login is valid */

     else if (check_password(password))

     {

          sm_jclose();

                   /*close current (2nd) login window */

          sm_emsg("Please reenter login");

     }

     else

          sm_jwindow("login3");

     return (0);

}

 

 

}


 

NAME

 

     sm_jwindow - display a window at a given position under

                      JAM control

 

SYNOPSIS

 

     int sm_jwindow (screen_arg)

     char *screen_arg;

 

DESCRIPTION

 

Displays screen_arg with its upper left-hand corner at the current cursor

position, if no line and column are specified. The function's argument can

include a specification of the display position (for instance, ("wind1 10 20").

The line and column are counted from one.  The display takes place under JAM

control. JAM can also close the window through a call to sm_jclose.

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the topmost,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

RETURNS

 

     0 if no error occurred during display of the screen; -1 if the screen

          file's format is incorrect; -2 if the form cannot be found; -3 if the

          system ran out of memory but the previous screen was restored; -7 if

          the screen was larger than the physical display, and there were fields

          that would have fallen outside the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_window (name);

     sm_jform (name);

     sm_jclose ();


 

EXAMPLE

 

/* This is an example of a caret function attached to the XMIT key.*/

/* Here we have completed entering data on the second of several */

/* security screens. If the user entered "bypass" into the login, */

/* he bypasses the other security screens, and the "welcome" */

/* screen is displayed. If the user login is incorrect, the */

/* current window is closed, and the user is back at the */

/* initial screen (below). Otherwise, the next security window */

/* is displayed. */

 

int getlogin(jptr)

char *jptr;

{

     char password[10];

     sm_n_getfield(password, "password");

     /* check if "bypass" has been entered into login */

     if (strcmp(password,"bypass"))

          sm_jform("welcome");

     /* check if login is valid */

     else if (check_password(password))

     {

          sm_jclose();

                   /*close current (2nd) login window */

          sm_emsg("Please reenter login");

     }

     else

          sm_jwindow("login3");

     return (0);

}


 

NAME

 

     sm_keyfilter - control keystroke record/playback filtering

 

SYNOPSIS

 

     int sm_keyfilter (flag)

     int flag;

 

DESCRIPTION

 

This function turns the keystroke record/playback mechanism of sm_getkey on

(flag = 1) or off (flag = 0). If none of the recording hooks have functions on

them, turning them on has no effect.

 

It returns a flag indicating whether recording was previously on or off.

 

RETURNS

 

     The previous value of the filter flag.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_getkey ();

     sm_u_avail (interval);

     sm_u_play ();

     sm_u_record (key);

 

EXAMPLE

 

/* Disable key recording and playback. */

 

sm_keyfilter (0);


 

NAME

 

     sm_keyhit - test whether a key has been typed ahead

 

SYNOPSIS

 

     int sm_keyhit (interval)

     int interval;

 

DESCRIPTION

 

This routine checks whether a key has already been hit; if so, it returns 1

immediately. If not, it waits for the indicated interval and checks again. The

key (if any is struck) is not read in, and is available to the usual keyboard

input routines.

 

Interval is in tenths of seconds; the exact length of the wait depends on the

granularity of the system clock, and is hardware- and operating-system

dependent. JAM uses this function to decide when to call the user-supplied

asynchronous function.

 

If the operating system does not support reads with timeout, this function

ignores the interval and only returns 1 if a key has been typed ahead.

 

RETURNS

 

     1 if a key is available, 0 if not.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_getkey ();

     sm_u_async ();

     sm_u_avail (interval);

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* The following code adds one asterisk per second to a

 * danger bar, until somebody presses EXIT. */

 

static char *danger_bar = "*************************";

int k;

 

sm_d_msg_line ("You have 25 seconds to find the EXIT key.", WHITE);

sm_do_region (5, 10, 25, WHITE, "");  /* Clear the danger bar area */

sm_flush ();

 

for (k = 1; k <= 25; ++k)

{

     if (sm_keyhit (10))

     {

          if (sm_getkey () == EXIT)

               break;

     }

     sm_do_region (5, 10, k, WHITE, danger_bar);

     sm_flush ();

}

if (k <= 25)

     sm_d_msg_line ("%BCongratulations! you win!");

else sm_err_reset ("Sorry, you lose.");


 

NAME

 

 

     sm_keyinit - initialize key translation table

 

SYNOPSIS

 

     int sm_keyinit (key_file)

     char key_file[];

 

DESCRIPTION

 

This routine is called by sm_initcrt as part of the initialization process, but

it can also be called by an application program (either before or after

sm_initcrt) to install a memory-resident key translation file.

 

To install a memory-resident key translation file, key_file must contain the

address of a key translation table created using the JYACC key2bin and bin2c

utilities, q.v. If it is zero, a disk file whose name is obtained from the SMKEY

variable will be used instead.

 

If no memory-resident file is supplied and an error occurs while reading the

disk file, this function prints out an error message and exits to the operating

system.

 

RETURNS

 

     0 if the key file is successfully installed; -1 if a disk file is requested

          and the terminal type is unknown; program exit if an error occurs

          while reading a disk file.

 

EXAMPLE

 

/* Install a memory-resident key file */

 

extern char keyfile[];

 

sm_keyinit (keyfile);


 

NAME

 

 

     sm_keylabel - get the printable name of a logical key

 

SYNOPSIS

 

     #include "smkeys.h"

 

     char *sm_keylabel (key)

     int key;

 

DESCRIPTION

 

Returns the label defined for key in the key translation file; the label is

usually what is printed on the key on the physical keyboard. If there is no such

label, returns the name of the logical key from the following table. Here is a

list of key mnemonics:

 

          EXIT    XMIT   HELP    BKSP   TAB

          NL      BACK   HOME    DELE   INS

          LP      FERA   CLR     SPGU   SPGD

          LARR    RARR   DARR    UARR   REFR

          EMOH    INSL   DELL    ZOOM   FHLP

          CAPS    ABORT

 

 

If the key code is invalid (not one defined in smkeys.h ), this function returns

the empty string.

 

RETURNS

 

     A string naming the key, or the empty string if it has no name.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_keyname (key);

 

EXAMPLE

 

#include "smkeys.h"

 

/* Put the name of the TRANSMIT key into a field

 * for help purposes. */

 

char buf[80];

 

sprintf (buf, "Press %s to commit the transaction.",

     sm_keylabel (XMIT));

sm_n_putfield ("help", buf);


 

NAME

 

     sm_l_at_cur - display a library-resident window at the current cursor

                   position

 

SYNOPSIS

 

     int sm_l_at_cur (lib_desc, screen_name)

     int lib_desc;

     char *screen_name;

 

DESCRIPTION

 

Displays a library-resident window at the current cursor position, offset by one

line to avoid hiding that line's contents.

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

A screen library is a single file containing many screens. You can assemble one

from individual screen files using the screen librarian, JYACC formlib.

Libraries provide a convenient way of distributing a large number of screens

with an application, and can improve efficiency by cutting down on filesystem

path searches.

 

The library descriptor is an integer returned by sm_l_open, which you must call

before trying to read any screens from a library. Note that sm_r_window and

related functions also search any open screen libraries.

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 is returned if no error occurred during display of the window. -2 is

          returned if lib_desc is invalid, or if that library does not contain

          screen_name. -3 is returned if a malloc failed to find available

          memory before the screen area was cleared, or if a malloc or read

          error occurred after the area was cleared but the screen was

          subsequently restored. -6 is returned if the screen library is

          corrupted.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_l_open (library_name);

     sm_l_form (library_descriptor, screen_name);

     sm_l_window (library_descriptor, screen_name, line, column);

     sm_l_close (library_descriptor);

EXAMPLE

 

/* Bring up a window from a library. */

 

int ld;

 

if ((ld = sm_l_open ("myforms")) < 0)

     sm_cancel ();

...

sm_l_at_cur (ld, "popup");


 

NAME

 

     sm_l_close - close a screen library

 

SYNOPSIS

 

     int sm_l_close (lib_desc)

     int lib_desc;

 

DESCRIPTION

 

Closes the screen library indicated by lib_desc and frees all associated memory.

The library descriptor is a number returned by a previous call to sm_l_open.

 

RETURNS

 

     -1 is returned if the library file could not be closed; -2 is returned if

          the library was not open; 0 is returned if the library was closed

          successfully.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_l_open (library_name);

     sm_l_at_cur (library_descriptor, screen_name);

     sm_l_form (library_descriptor, screen_name);

     sm_l_window (library_descriptor, screen_name, line, column);

 

EXAMPLE

 

/* Bring up a window from a library. */

 

int ld;

 

if ((ld = sm_l_open ("myforms")) < 0)

     sm_cancel ();

...

sm_l_at_cur (ld, "popup");

...

sm_l_close (ld);


 

NAME

 

     sm_l_form - display a library-resident screen as a base form

 

SYNOPSIS

 

     int sm_l_form (lib_desc, screen_name)

     int lib_desc;

     char *screen_name;

 

DESCRIPTION

 

This function displays a library-resident screen as a base form.

 

Bringing up a screen as a form causes the previously displayed form and windows

to be discarded, and their memory freed. The new screen is displayed with its

upper left-hand corner at the extreme upper left of the display (position (0,

0)). Any error in this function leaves the display and JAM internals in an

undefined state.

 

If the form contains display data that are too big for the physical display,

they are truncated without warning. However, if there are fields that won't fit

within the physical display, this function returns an error without displaying

the form.

 

A screen library is a single file containing many screens. You can assemble one

from individual screen files using the screen librarian, JYACC formlib.

Libraries provide a convenient way of distributing a large number of screens

with an application, and can improve efficiency by cutting down on filesystem

path searches.

 

The library descriptor is an integer returned by sm_l_open, which you must call

before trying to read any screens from a library. Note that sm_r_window and

related functions also search any open screen libraries.

 

This function should be called by JAM applications only under unusual

circumstances, as it does not update the control stack. You should execute a

control string to display the form instead.

 

RETURNS

 

     0 is returned if no error occurred during display of the screen. -2 is

          returned if lib_desc is invalid, or does not contain screen_name. -4

          is returned if, after the screen has been cleared, the form cannot be

          displayed successfully because of a read error. -5 is returned if,

          after the screen has been cleared,not enough memory is available. -6

          is returned if the library is corrupt.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_l_window (library_descriptor, screen_name, line, column);

     sm_l_at_cur (library_descriptor, screen_name);

     sm_l_open (library_name);

     sm_l_close (library_descriptor);

 

EXAMPLE

 

/* Put up a base form from a previously opened library. */

 

extern int formlib1;

 

if (sm_l_form (formlib1, "background"))

     sm_cancel ();


 

NAME

 

     sm_l_open - open a screen library

 

SYNOPSIS

 

     int sm_l_open (lib_name)

     char *lib_name;

 

DESCRIPTION

 

Opens a screen library created by JYACC formlib, preparatory to displaying

screens therein. It allocates space to store information about the library,

leaves the library file open, and returns a descriptor identifying the library.

That descriptor may subsequently be used by sm_l_window and related functions,

to display screens stored in the library; or the library can be referenced

implicitly by sm_r_window and related functions, which search all open screen

libraries.

 

The library file is sought in all the directories identified by SMPATH and the

parameter to sm_initcrt. Defining the SMFLIBS variable in your setup file to a

list of library names will cause this function to be called on the libraries;

all will then be searched automatically by sm_r_window and variants.

 

Several libraries may be kept open at once. This may cause problems on systems

with severe limits on memory or simultaneously open files.

 

RETURNS

 

     -1 if the library cannot be opened or read; -2 if too many libraries are

          already open; -3 if the named file is not a library; -4 if

          insufficient memory is available; Otherwise, a non-negative integer

          that identifies the library file.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_l_form (library_descriptor, screen_name);

     sm_l_at_cur (library_descriptor, screen_name);

     sm_l_window (library_descriptor, screen_name, line, column);

     sm_l_close (library_descriptor);

     sm_r_window (screen_name, line, column);

 

EXAMPLE

 

/* Prompt for the name of a screen library until a

 * valid one is found. Assume the memory-resident

 * screen contains one field for entering the library name,

 * with suitable instructions. */

 

int ld;

extern char libquery[];

 

if (sm_d_form (libquery) < 0)

     sm_cancel ();

sm_d_msg_line ("Please enter the name of your screen library.");

 

do {

     sm_openkeybd ();

} while ((ld = sm_l_open (sm_fptr (1))) < 0);


 

NAME

 

     sm_l_window - display a library-resident window at a given location

 

SYNOPSIS

 

     int sm_l_window (lib_desc, screen_name, start_line, start_column)

     int lib_desc, start_line, start_column;

     char *screen_name;

 

DESCRIPTION

 

The screen screen_name is read from the library indicated by lib_desc, and

displayed with its upper left-hand corner at (line, column). The line and column

are counted from zero: if line is 1, the screen is displayed starting at the

second line of the screen.

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

A screen library is a single file containing many screens. You can assemble one

from individual screen files using the screen librarian, JYACC formlib.

Libraries provide a convenient way of distributing a large number of screens

with an application, and can improve efficiency by cutting down on filesystem

path searches.

 

The library descriptor is an integer returned by sm_l_open, which you must call

before trying to read any screens from a library. Note that sm_r_window and

related functions also search any open screen libraries.

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 is returned if no error occurred during display of the form. -1 is

          returned if the window could not be displayed successfully because the

          format was incorrect. -2 is returned if lib_desc is invalid, or does

          not contain screen_name. -3 is returned if the system ran out of

          memory but the screen was restored successfully.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_l_open (library_name);

     sm_l_form (library_descriptor, screen_name);

     sm_l_at_cur (library_descriptor, screen_name);

     sm_l_close (library_descriptor);

     sm_r_window (screen_name, line, column);

EXAMPLE

 

/* Bring up a window from a library. */

 

int ld;

 

if ((ld = sm_l_open ("myforms")) < 0)

     sm_cancel ();

...

sm_l_window (ld, "popup", 5, 22);

...

sm_l_close (ld);


 

NAME

 

     sm_label_key - put a function key block label onto the screen

 

SYNOPSIS

 

 

     int sm_label_key (label_number, line1_text,

          line2_text)

     int label_number;

     char *line1_text, *line2_text;

 

DESCRIPTION

 

Certain terminals provide special areas on the screen to hold descriptions of

function key actions. This routine places a label into one of those blocks.

Label_number tells which block to use; the two strings will be placed on line 1

and line 2 of the block. (For a blank line, pass the empty string.)

 

This function assumes that there are two lines available per block. The KPAR and

KSET entries must be present in the video file in order for this routine to

work. Refer to the video manual in the Configuration Guide for instructions.

 

RETURNS

 

     -1 if the label number is out of range, 0 otherwise.

 

EXAMPLE

 

/* Put any old label into the first two function key blocks. */

 

     sm_label_key(1, "blk1, ln1", "blk1, ln2");

     sm_label_key(2, "blk2, ln1", "blk2, ln2");


 

NAME

 

     sm_last - position the cursor in the last field

 

SYNOPSIS

 

     void sm_last ();

 

DESCRIPTION

 

Places the cursor at the first enterable position of the last unprotected field

of the current form. The first enterable position is the leftmost in a

left-justified field, and the rightmost in a right-justified field; furthermore,

if the field is digits-only, punctuation characters will be skipped.

 

Unlike sm_home, this function will not reposition the cursor if the screen has

no unprotected fields.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_home ();

     sm_gofield (field_number);

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Assume the last field must be entered for confirmation.

 * This code puts the cursor there, after the TRANSMIT key

 * is pressed. */

 

while (sm_openkeybd () != XMIT)

     ;

sm_unprotect (sm_numflds);

sm_last ();

sm_openkeybd ();

if (sm_is_yes (sm_numflds))

     commit ();  /* Finish whatever it is */


 

NAME

 

     sm_lclear - erase LDB entries of one scope

 

SYNOPSIS

 

     int sm_lclear (scope)

     int scope;

 

DESCRIPTION

 

This function erases the values stored in the local data block for all names

having a scope of scope; legal values are between 1 and 9. Constant variables

having scope 1 can be erased.

 

Refer to the Author's Guide for a discussion of the scope of LDB entries.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_lreset (file_name, scope);

 

EXAMPLE

 

/* Clear out LDB entries of scope 6, which has been

 * assigned to customer information. */

 

#define CUSTOMER_SCOPE 6

 

sm_lclear (CUSTOMER_SCOPE);


 

NAME

 

     sm_ldb_init - initialize (or reinitialize) the local data block

 

SYNOPSIS

 

     void sm_ldb_init ();

 

DESCRIPTION

 

This function creates an empty index of named data items by reading the data

dictionary, then loads values into them from initialization files. There is no

LDB prior to the execution of this function.

 

Selected parts of the LDB, namely those assigned a certain scope, can be

reinitialized using sm_lclear or sm_lreset.

 

This function is called automatically during JAM initalization. Other functions

that affect its behavior, such as sm_dicname and sm_ininames, should be called

first.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_lreset (filename, scope);

     sm_ininames (file_list);

     sm_dicname (dictionary_name);

 

EXAMPLE

 

/* After a catastrophic application failure, reboot the index. */

if (bad_data ())

{

     sm_ldb_init ();

     ...

}


 

NAME

 

     sm_leave - prepare to leave a JAM application temporarily

 

SYNOPSIS

 

     void sm_leave ();

 

DESCRIPTION

 

It may at times be necessary to leave a JAM application temporarily: to escape

to the command interpreter, to execute some graphics functions, and so on. In

such a case, the terminal and its operating system channel need to be restored

to their normal states.

 

This function should be called before leaving. It clears the physical screen

(but not the internal screen image); resets the operating system channel; and

resets the terminal (using the RESET sequence found in the video file).

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_return ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Escape to the UNIX shell for a directory listing */

 

sm_leave ();

system ("ls -l");

sm_return ();

sm_c_off ();

sm_d_msg_line ("Hit any key to continue", BLINK | WHITE);

sm_getkey ();

sm_d_msg_line ("", WHITE);

sm_rescreen ();


 

NAME

 

     sm_length - get the maximum length of a field

 

SYNOPSIS

 

     int sm_length (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the maximum length of the field specified by field_number. If the field

is shiftable, its maximum shifting length is returned. This length is as defined

in jxform, and has no relation to the current contents of the field; use

sm_dlength to get the length of the contents.

 

RETURNS

 

     Length of the field, or 0 if the field is not found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_length (field_name);

     sm_dlength (field-number);

 

EXAMPLE

 

/* Compute the number of blanks left in a

 * right-justified field (number 6), and fill them

 * with asterisks. */

 

int blanks, k;

char buf[256];

 

blanks = sm_length (6) - sm_dlength (6);

for (k = 0; k < blanks; ++k)

     buf[k] = '*';

sm_getfield (buf + blanks, 6);

sm_putfield (6, buf);


 

NAME

 

 

     sm_lngval - get the long integer value of a field

 

SYNOPSIS

 

     #include "smdefs.h"

 

     long sm_lngval (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the contents of field_number, converted to a long integer. All non-digit

characters are ignored, except of course for a leading plus or minus sign.

 

RETURNS

 

     The long value of the field; 0 if the field is not found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_lngval (field_name, element);

     sm_i_lngval (field_name, occurrence);

     sm_n_lngval (field_name);

     sm_o_lngval (field_number, occurrence);

     sm_intval (field_number);

     sm_ltofield (field_number, value);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Retrieve the number of fish in one particular sea

 * (a big number) from the screen. */

 

#define MEDITERRANEAN 4

long fish;

 

fish = sm_e_lngval ("seas", MEDITERRANEAN);


 

NAME

 

     sm_lreset - reinitialize LDB entries of one scope

 

SYNOPSIS

 

     int sm_lreset (file_name, scope)

     char *file_name;

     int scope;

 

DESCRIPTION

 

This function sets local data block entries to values read from file_name. Scope

must be between 1 and 9; references in the file to LDB entries not belonging to

scope are ignored. All variables belonging to scope are cleared before

reinitializing; therefore, this function erases variables that are not in the

file.

 

The file may be in the current directory, or in any of the directories listed in

the SMPATH environment variable. It contains pairs of names with values, each

enclosed in quotes. While all whitespace outside the quotes is ignored, we

recommend for readability that the file have one name-value pair per line. If an

entry has multiple occurrences, it may be subscripted in the file. Here are a

few sample pairs:

 

     "husband" "Ronald Reagan"

     "wife[1]" "Jane Wyman"

     "wife[2]" "Nancy Davis"

 

If you plan to use this function, we recommend that you group your variables in

separate files by scope. You can use sm_ininames to list a number of files for

initialization.

 

RETURNS

 

     -1 if error (file not found or scope out of range), 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_lclear (scope);

 

EXAMPLE

 

/* Reinitialize LDB entries of scope 6, which has been

 * assigned to customer information. */

 

#define CUSTOMER_SCOPE 6

#define CUSTOMER_INIT  "customers.ini"

 

sm_lreset (CUSTOMER_INIT, CUSTOMER_SCOPE);


 

NAME

 

     sm_lstore - copy everything from screen to LDB

 

SYNOPSIS

 

     int sm_lstore ();

 

DESCRIPTION

 

Copies data from the screen to local data block entries with matching names. In

its loop, this function makes use of a data structure set up during screen

display that identifies which fields have LDB entries.

 

This function is similar to the Release 3 function ldb_store. It is called

automatically by the JAM screen display logic, when bringing up a new screen,

and need not be called by application code except under special circumstances.

 

RETURNS

 

     -3 if sufficient memory is not available, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_allget (respect_flag);


 

NAME

 

 

     sm_ltofield - place a long integer in a field

 

SYNOPSIS

 

     int sm_ltofield (field_number, value)

     int field_number;

     long value;

 

DESCRIPTION

 

The long integer passed to this routine is converted to human-readable form and

placed in field_number. If the number is longer than the field, it is truncated

without warning, on the right or left depending on the field's justification.

 

RETURNS

 

     -1 if the field is not found. 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_ltofield (field_name, element, value);

     sm_i_ltofield (field_name, occurrence, value);

     sm_n_ltofield (field_name, value);

     sm_o_ltofield (field_number, occurrence, value);

     sm_lngval (field_number);

     sm_itofield (field_number, value);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Set the number of fish in the sea to a smallish number. */

 

#define MEDITERRANEAN 4

 

sm_e_ltofield ("seas", MEDITERRANEAN, 14L);


 

NAME

 

     sm_m_flush - flush the message line

 

SYNOPSIS

 

     void sm_m_flush ();

 

DESCRIPTION

 

Forces updates to the message line to be written to the display. This is useful

if you want to display the status of an operation with sm_d_msg_line, without

flushing the entire display as sm_flush does.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_flush ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Process a big pile of records, providing status as we go. */

char buf[80];

int k;

 

k = 0;

do {

     sprintf (buf, "Processing record %d", k + 1);

     sm_d_msg_line (buf, REVERSE | WHITE);

     sm_m_flush ();

} while (process (records[k++]) >= 0);


 

NAME

 

     sm_max_occur - get the maximum number of occurrences that can be

                    entered into an array or field

 

SYNOPSIS

 

     int sm_max_occur (field_number)

     int field_number;

 

DESCRIPTION

 

If the field or array designated by field_number is scrollable, returns the

maximum number of items the scroll can hold. Note that this is the maximum as

defined by jxform or a call to sm_sc_max, not the greatest number actually

entered so far.

 

If the field is an element of a non-scrollable array, the function returns the

number of elements in the array. If it is a non-scrollable single field, the

function returns 1.

 

RETURNS

 

     0 if the field designation is invalid; 1 for a non-scrollable single field;

          The number of elements in a non-scrollable array; The maximum number

          of items in a scrollable array or field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_max_occur (field_name);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Find the number of occurrences in an array of

 * whole numbers, say numbers of children, and

 * allocate some memory to hold them. */

 

int *children, howmany;

 

if ((howmany = sm_n_max_occur ("children")) > 0)

     children = (int *)calloc(howmany, sizeof(int));


 

NAME

 

     sm_menu_proc - get a menu selection

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_menu_proc (type)

     int type;

 

DESCRIPTION

 

Allows you to tab, backtab, arrow, and scroll through a menu screen, and select

an item from it. The entry under the cursor is displayed in reverse video. The

routine returns to the calling program when you hit EXIT or a function key (PF,

SPF, or APP), or make a selection. A selection is made when you hit the TRANSMIT

key, or a sequence of characters that uniquely match a menu entry (see

mp_string).

 

Hitting a key that matches the first character of a menu entry on the screen

causes the cursor to be positioned to that entry. If type is UPPER (or LOWER),

any alphabetic keyboard entry is translated to upper (or lower) case before a

match is attempted. If type contains both UPPER and LOWER, both translations are

tried; the search is totally insensitive to case. Any other value yields a

case-sensitive search. The search always starts at the beginning of the menu,

and ignores off-screen data; to see off-screen menu items you must use the

scrolling keys.

 

Each menu selection must be defined as initial data in a tab-unprotected menu

field. Furthermore, unless you change the default setting by calling mp_string,

each selection must begin with a unique character.( The JAM run-time system does

so during its standard initialization sequence. You can define arbitrary return

codes for each field using jxform; the default is to use the first character of

the menu entry itself. See the JAM Author's Guide for a detailed discussion of

menu creation and return values.

 

Two auxiliary functions, mp_options and mp_string, can alter the behavior of the

cursor; refer to their definitions.

 

Menu control strings are not executed within this function, but at a higher

level of the JAM run-time system. If you call this function, do not expect your

selection's control string to be executed.

 

 

RETURNS

 

     If the cursor is not within a field, returns 0. The translated value (see

          smkeys.h ) of EXIT, or of any other function key except TRANSMIT. If a

          selection is made with TRANSMIT or a menu character, the menu return

          code defined in jxform, or the first character of the selected entry

          if there is no return code.

 

EXAMPLE

 

See sm_mp_string for an example.


 

NAME

 

     sm_mp_options - define cursor motion for sm_menu_proc

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_mp_options (wrap, vertical_arrow,

          horizontal_arrow)

     int wrap, vertical_arrow, horizontal_arrow;

 

DESCRIPTION

 

This function takes three parameters. Wrap determines whether the arrow keys

wrap, that is, whether the cursor procedes from the rightmost field around to

the leftmost on right arrow (and so forth). The TAB and BACKTAB keys always

wrap. Vertical_arrow and horizontal_arrow influence which field the arrow keys

land you in when wrapping is not imminent. If you want to leave any of the

settings unchanged, pass the special value OK_NOCHANGE.

 

The mnemonics listed below are defined in smdefs.h ; they are the same as those

used by ok_options.

 

   wrap:

   OK_NOWRAP         No wrapping. The terminal beeps if an attempt is made to

                     arrow past the edge of the current form (or window).

                     OK_NOWRAP is overridden by OK_TAB and equivalent

                     settings.

   OK_WRAP           Default. The arrow keys wrap. Vertical arrows wrap

                     straight from bottom to top and vice versa; right arrow

                     wraps to the beginning of the next (or first) line, left

                     arrow to the end of the previous (or last) line.

 

   vertical arrow (up- and down-arrow keys):

   OK_NXTLINE        The cursor will be positioned to the closest field whose

                     line is closest to the current line.

   OK_FREE           Default. Same as OK_NXTLINE.

   OK_RESTRICT       The arrow keys are not operative; the terminal will beep

                     if they are pressed.

   OK_SWATH          The cursor will be positioned to the closest field that

                     overlaps the "swath" containing the current field.

   OK_COLM           Same as OK_SWATH.

   OK_NXTFLD         The cursor will be positioned to the field closest to

                     the current line and column. The calculation uses the

                     diagonal distance, assuming that the terminal has a 5 to

                     2 aspect ratio.

   OK_TAB            The arrow keys behave like TAB and BACKTAB.

 

   horizontal arrow (left- and right-arrow keys):

   OK_TAB            The arrow keys behave like TAB and BACKTAB.

   OK_FREE           Default. Same as OK_TAB.

   OK_RESTRICT       The arrow keys are not operative.

   OK_COLM           The cursor will be positioned to the closest field on

                     the current line.

   OK_SWATH          Same as OK_COLM.

   OK_NXTLINE        The cursor will be positioned to the closest of those

                     fields whose column is closest to the current column.

   OK_NXTFLD         The cursor will be positioned to the field closest to

                     the current line and column.  The calculation uses the

                     diagonal distance, assuming that the terminal has a 5 to

                     2 aspect ratio.


 

If you define the SMMPOPTIONS variable in your setup file, it will cause this

function to be called automatically during start-up with the parameters you

specify there.

 

RETURNS

 

     -1 if any parameter is invalid (nothing is changed); 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_menu_proc (type);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Restore the menu_proc options to their default values. */

 

if (sm_mp_options (OK_WRAP,OK_FREE,OK_FREE))

     sm_cancel ();

}


 

NAME

 

     sm_mp_string - set string option for sm_menu_proc

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_mp_string (option)

     int option;

 

DESCRIPTION

 

Sets the string option for sm_menu_proc to one of the following values. The

mnemonics are defined in smdefs.h .

 

If option is OK_NOSTRING (the default), each data key struck is compared against

the initial character of each menu item, beginning with the first. As soon as a

match is found that entry is selected, regardless of whether there are other

items that begin with the same character; therefore, the second and subsequent

duplicate entries can never be selected by a data key.

 

If option is OK_STRING, data keys are collected until the saved sequence is long

enough to match one menu item unambiguously. As keys are collected, the cursor

moves to the item closest to the top that matches everything typed so far.

 

If you define the SMMPSTRING variable in your setup file, it will cause this

function to be called automatically during start-up with the parameter you

specify there.

 

Suppose a menu contains the following items, and the string option is on:

 

                              ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»

                              º                 º

                              º AAA Auto        º

                              º Ace Body Work   º

                              º Acme Auto Parts º

                              º                 º

                              ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ

 

Typing a positions the bounce bar to the first item; typing c moves to the

second; typing m moves to the third and selects it. Typing aa selects the first

item.

 

RETURNS

 

     -1 if the option is invalid, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_menu_proc (type);

 

EXAMPLE

 

See above.


 

NAME

 

     sm_msg - display a message at a given column on the status line

 

SYNOPSIS

 

     void sm_msg (column, length, text)

     int column, length;

     char *text;

 

DESCRIPTION

 

The message is merged with the current contents of the status line, and

displayed beginning at column. Length gives the number of characters in text.

 

On terminals with onscreen attributes, the column position may need to be

adjusted to allow for attributes embedded in the status line. Refer to

sm_d_msg_line for an explanation of how to embed attributes and function key

names in a status line message.

 

This function is called, for example, by the function that updates the cursor

position display (see sm_c_vis).

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_msg_line (msg);

 

EXAMPLE

 

#include "smdefs.h"

 

/* This code displays a message, then chops out

 * part of it. */

 

char *text0 = "        ";

char *text1 = "Message is displayed on the status line at col 1.";

 

sm_msg(1, strlen(text1), text1);

sm_msg(12, strlen(text0), text0);


 

NAME

 

     sm_msg_get - find a message given its number

 

SYNOPSIS

 

     #include "smdefs.h"

     #include "smerror.h"

 

     void *sm_msg_get (number)

     int number;

 

DESCRIPTION

 

The messages used by JAM library routines are stored in binary message files,

which are created from text files by the JYACC msg2bin utility. Use sm_msgread

to load message files for use by this function.

 

This function takes the number of the message desired and returns the message,

or a less informative string if the message number cannot be matched.

 

Messages are divided into classes based on their numbers, with up to 4096

messages per class. The message class is the message number divided by 4096, and

the message offset within the class is the message number modulo 4096.

Predefined JAM message numbers and classes are defined in smerror.h .

 

RETURNS

 

     The desired message, if found; the message class and number, as a string,

          otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_msgfind (number);

     sm_msgread ();

 

EXAMPLE

 

#include "smdefs.h"

#include "smerror.h"

 

/* Assume that an anxious programmer has just typed

 * in the question, "Will my boss like my new program?"

 * This code fragment answers the question. */

 

sm_n_putfield ("answer", rand() & 1 ?

     sm_msg_get (SM_YES) :

     sm_msg_get (SM_NO));


 

NAME

 

 

     sm_msgfind - find a message given its number

 

SYNOPSIS

 

     #include "smdefs.h"

     #include "smerror.h"

 

     char *sm_msgfind (number)

     int number;

 

DESCRIPTION

 

This function takes the number of a screen manager message, and returns the

message string. It is identical to sm_msg_get, except that it returns zero if

the message number is not found.

 

Screen manager message numbers are defined in smerror.h .

 

RETURNS

 

     The message, or 0 if the message number is out of range.

 

EXAMPLE

 

#include "smdefs.h"

#include "smerror.h"

 

/* print out message #4 */

 

sprintf (buf, "The message reads: %s\n", sm_msgfind (SM_BADKEY));

sm_quiet_err (buf);


 

NAME

 

 

     sm_msgread - read message file into memory

 

SYNOPSIS

 

     #include "smerror.h"

 

     int sm_msgread (code, class, mode, arg)

     char *code;

     int class;

     int mode;

     char *arg;

 

DESCRIPTION

 

Reads a single set of messages from a binary message file into memory, after

which they can be accessed using sm_msg_get and sm_msgfind. Code selects a

single message class from a file that may contain several classes:

 

     Code    Class       Contents

 

     SM      SM_MSGS     Screen manager messages

     FM      FM_MSGS     Formaker (xform) messages

     JM      JM_MSGS     JAM run-time messages

     JX      JX_MSGS     JAM Formaker (jxform) messages

     (blank)             Undesignated user messages

 

 

Class identifies a class of messages. Classes 0-7 are reserved for user

messages, and several classes are reserved to JAM; see smerror.h . As messages

with the prefix code are read from the file, they are assigned numbers

sequentially beginning at 4096 times class.

 

Mode is a mnemonic or mnemonics drawn from the following list. The first five

indicate where to get the message file; at least one of these must be supplied.

The other four modify the basic action.

 

     Mnemonic          Action

 

     MSG_DELETE        Delete the message class and

                       recover its memory.

     MSG_DEFAULT       Use the default file defined by the

                       SMMSGS setup variable.

     MSG_FILENAME      Use a file named in arg.

     MSG_ENVIRON       Use the file named in an environment

                       variable named by arg.

     MSG_MEMORY        Use a memory-resident file whose address

                       is given by arg.

 

     MSG_NOREPLACE     Modifier: do not overwrite previously

                       installed messages.

     MSG_DSK           Modifier: leave file open, do not read into

                       memory

     MSG_INIT          Modifier: do not use screen manager

                       error reporting.

     MSG_QUIET         Modifier: do not report errors.

 

 

You can or MSG_NOREPLACE with any mode except MSG_DELETE, to prevent overwriting

messages read previously. Error messages will be displayed on the status line,

if the screen has been initialized by sm_initcrt; otherwise, they will go to the

standard error output. You can or MSG_INIT with the mode to force error messages

to standard error. Combining the mode with MSG_QUIET suppresses error reporting

altogether.

 

If you or MSG_DSK with the mode, the messages are not read into memory. Instead

the file is left open, and sm_msg_get and sm_msgfind fetch them from disk when

requested. If your message file is large, this can save substantial memory; but

you should remember to account for operating system file buffers in your

calculations.

 

Arg contains the environment variable name for MSG_ENVIRON; the file name for

MSG_FILENAME; or the address of the memory-resident file for MSG_MEMORY. It may

be passed as zero for other modes.

 

RETURNS

 

     0 if the operation completed successfully; 1 if the message class was

          already in memory and the mode included MSG_NOREPLACE; 2 if the mode

          was MSG_DELETE and the message file was not in memory; -1 if the mode

          was MSG_ENVIRON or MSG_DEFAULT and the environment variable was

          undefined; -2 if the mode was MSG_ENVIRON, MSG_FILENAME, or

          MSG_DEFAULT and the message file could not be read from disk; other

          negative values if the message file was bad or insufficient memory was

          available.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_msg_get (number);

     sm_msgfind (number);

 

EXAMPLE

 

#include "smdefs.h"

#include "smerror.h"

 

/****************** Example 1 **********************

 * These calls are issued by sm_initcrt() to load

 * standard messages and one set of user messages. */

 

sm_msgread ("SM", SM_MSGS, MSG_DEFAULT, (char *)0);

sm_msgread ("", 0, MSG_DEFAULT, (char *)0);

 

/***************** Example 2 ***********************

 * This code fragment duplicates the Release 3 routine

 * sm_msginit(). */

 

int sm_msginit (memfile)

char memfile[];

{

int sm_msginit (msg_file)

char * msg_file;

{

     int mode = (msg_file ? MSG_MEMORY : MSG_DEFAULT | MSG_NOREPLACE)

          | MSG_INIT;

 

     if ( sm_msgread ("SM", SM_MSGS, mode, msg_file) < 0 ||

          sm_msgread ("JM", JM_MSGS, mode, msg_file) < 0 ||

          sm_msgread ("FM", FM_MSGS, mode, msg_file) < 0 ||

          sm_msgread ("JX", JX_MSGS, mode, msg_file) < 0)

     {

          exit (RET_FATAL);

     }

     sm_msgread ((char *)0, 0, mode & ~MSG_INIT | MSG_QUIET, msg_file);

     return (0);

}

NAME

 

     sm_mwindow - display a status message in a window

 

SYNOPSIS

 

     int sm_mwindow (text, line, column)

     char *text;

     int line;

     int column;

 

DESCRIPTION

 

This function displays text in a pop-up window, whose upper left-hand corner

appears at line and column. The line and column are counted from zero: if line

is 1, the top of the window will be on the second line of the display. The

window itself is constructed on the fly by the run-time system; no data entry is

possible in it, nor is data entry possible in underlying screens as long as it

is displayed. Make sure that sm_close_window is called after this function.

 

All the percent escapes for status messages, except %M, are effective; refer to

sm_d_msg_line for a list and full description. If either line or column is

negative, the window will be displayed according to the rules given at

sm_r_at_cur.

 

RETURNS

 

     -1 if there was a malloc failure. 1 if the text had to be truncated to fit

          in a window 0 otherwise

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_msg_line (text, attribute);

 

EXAMPLE

 

/* By judicious use of %N's, it is possible to get your

 * messages centered on the screen when you call

 * sm_mwindow().

 */

 

void poem ()

{

     sm_mwindow ("The world is too much with us. Late and soon,%N\

Getting and spending, we lay waste our powers.%N\

Little we see in Nature that is ours;%N\

We have given our hearts away, a sordid boon!%N%N\

The sea that bares her bosom to the Moon,%N\

The winds that will be raging at all hours,%N\

And are up-gathered now like sleeping flowers,%N\

For this, for everything, we are out of tune;%N\

It moves us not. Great God! I'd rather be%N\

A pagan, suckled in a creed outworn;%N\

So might I, standing on this pleasant lea,%N\

Have glimpses that would make me less forlorn:%N\

Catch sight of Proteus rising from the sea,%N\

Or hear old Triton blow his wreathed horn.",

     6, 16);

}


 

NAME

 

     sm_n_1clear_array   clear all data from a single scrolling array

                         sm_n_1protect

                         selectively protect a field sm_n_1unprotect

                         selectively unprotect a field sm_n_amt_format

                         format data and write to a field sm_n_aprotect

                         protect an entire array or scroll sm_n_aunprotect

                         unprotect an entire array or scroll sm_n_bitop

                         manipulate field edit bits sm_n_chg_attr

                         change the display attribute(s) of a field

                         sm_n_clear_array

                         clear all data from a scrolling array and parallel

                         arrays sm_n_dblval

                         get the decimal value of a field sm_n_dlength

                         get the length of data stored in a field sm_n_dtofield

                         write decimal value to a field sm_n_edit_ptr

                         get special edit sm_n_fldno

                         * see next page * sm_n_fptr

                         get copy of data in field sm_n_fval

                         force validation of a field sm_n_getfield

                         copy data from field into buffer sm_n_gofield

                         position cursor to a field sm_n_intval

                         get integer value of data in field sm_n_is_yes

                         test field for yes sm_n_itofield

                         write integer value to field sm_n_length

                         get length of field sm_n_lngval

                         get long integer value of data in field sm_n_ltofield

                         write long integer value to field sm_n_max_occur

                         get maximum occurrence of field sm_n_mdt_clear

                         reset field's MDT bit sm_n_mod_test

                         test field's MDT bit sm_n_novalbit

                         reset field's validated bit sm_n_num_items

                         get number of items entered in scrollable field or

                         array sm_n_off_gofield

                         move cursor to specified offset in a field

                         sm_n_protect

                         protect field from data entry sm_n_putfield

                         write data string to field sm_n_size_of_array

                         get number of elements in an array sm_n_unprotect

                         allow data entry into field sm_n_wselect

                         select a hidden window by name

 

DESCRIPTION

 

Each or the above functions accesses a field by means of the field name. For a

description of sm_n_fldno, see the next page. For a description of any other

function listed above, look under the related function without n_ in its name.

For example, sm_n_amt_format is described under sm_amt_format.  If the named

field is not on the screen, these functions will attempt to access a similarly

named entry in the local data block.


 

NAME

 

     sm_n_fldno - get the field number of a named field

 

SYNOPSIS

 

     int sm_n_fldno (field_name)

     char *field_name;

 

DESCRIPTION

 

Returns the field number of a field specified by name, or the base field number

of an array specified by name.

 

RETURNS

 

     An integer ranging from 1 to the maximum number of fields on the current

          form. 0 if the field name is not found.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_fldno (field_name, element)

 

EXAMPLE

 

#include "smdefs.h"

 

/* Write a list of real numbers to the screen. The first

 * and last fields in the list are tagged with special names.

 * Actually, sm_dtofield () would be more convenient.

 */

int k, first, last;

char buf[256];

double values[];

     /* set up elsewhere... */

 

last = sm_n_fldno ("last");

first = sm_n_fldno ("first");

for (k = first; k && k <= last; ++k)

{

     sprintf (buf, "%lf", values[k - first]);

     sm_amt_format (k, buf);

}


 

NAME

 

     sm_nl - tab to the first unprotected field beyond the current line

 

SYNOPSIS

 

     void sm_nl ();

 

DESCRIPTION

 

This function moves the cursor to the next item of a scrolling field or array,

scrolling if necessary. Unlike the down-arrow, it will open up a blank scrolling

item if there are no more below (but the maximum has not yet been exceeded).

 

If the current field is not scrolling, the cursor is positioned to the first

unprotected field, if any, following the current line of the form. If there are

no unprotected fields beyond there, the cursor is positioned to the first

unprotected field of the form.

 

If the form has no unprotected fields at all, the cursor is positioned to the

first column of the line following the current line; if the cursor is on the

last line of the form, it goes to the top left-hand corner of the form.

 

This function is ordinarily bound to the RETURN key.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_tab ();

     sm_home ();

     sm_last ();

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Scuttle down a scrolling array until we come

 * to a nonblank item, or run out of array. */

 

char buf[256];

 

while (sm_t_scroll (sm_fldnumber + 1) &&

     sm_getfield (buf, sm_fldnumber + 1) == 0)

{

     sm_nl ();

}


 

NAME

 

     sm_novalbit - forcibly invalidate a field

 

SYNOPSIS

 

     int sm_novalbit (field_number)

     int field_number;

 

DESCRIPTION

 

Resets the VALIDED bit of the specified field, so that the field will again be

subject to validation when it is next exited, or when the screen is validated as

a whole.

 

JAM sets a field's VALIDED bit automatically when the field passes all its

validations. The bit is initially clear, and is cleared whenever the field is

altered by keyboard input or by a library function such as sm_putfield.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_novalbit (field_name, element)

     sm_i_novalbit (field_name, occurrence)

     sm_n_novalbit (field_name)

     sm_o_novalbit (field_number, occurrence)

     sm_fieldval ();

     sm_s_val ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Here is a validation function for a "last_name"

 * field. When it is changed, it marks the

 * "first_name" field, which depends on it, invalid. */

 

int validate (field, data, occur, bits)

char *data;

{

     if (bits & VALIDED) /* Not really changed */

          return 0;

 

     sm_n_novalbit ("first_name");

     return 0;

}


 

NAME

 

     sm_num_occurs - count the occurrences in a scrollable field or array

 

SYNOPSIS

 

     int sm_num_occurs (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the number of items actually entered so far into the scrollable field or

array identified by field_number. They may have been entered either through the

keyboard, or through calls to sm_putfield or similar functions.

 

This count is different from the maximum capacity of a scroll, which you can

retrieve by calling sm_max_occur.

 

RETURNS

 

     -1 if the field is not found; otherwise, the number of items entered,

          possibly 0.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_num_occurs (field_name);

     sm_max_occur (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Compute the number of unused items in this scroll. */

 

int unused;

 

unused = sm_n_max_occur ("hatpins") -

     sm_n_num_occurs ("hatpins");


 

NAME

 

     sm_o_achg           change the display attribute of a scrolling item

                         sm_o_amt_format

                         format a currency value and write to occurrence

                         sm_o_bitop

                         manipulate an occurrence's edit bits sm_o_chg_attr

                         change the display attribute of a field sm_o_dblval

                         get decimal value of occurrence sm_o_dlength

                         get length of data in occurrence sm_o_doccur

                         delete an occurrence from an array or scroll

                         sm_o_dtofield

                         write decimal value to occurrence sm_o_fptr

                         get copy of occurrence's data sm_o_fval

                         force validation of an occurrence sm_o_getfield

                         copy data from occurrence into buffer sm_o_gofield

                         position cursor to occurrence sm_o_intval

                         get integer value of occurrence sm_o_ioccur

                         insert a blank occurrence into an array or scroll

                         sm_o_itofield

                         write integer value to occurrence sm_o_lngval

                         get long integer value of occurrence sm_o_ltofield

                         write long integer value to occurrence sm_o_mdt_clear

                         reset MDT bit of an occurrence sm_o_mod_test

                         test MDT bit of an occurrence sm_o_novalbit

                         reset validated bit of an occurrence sm_o_off_gofield

                         place the cursor in the middle of an occurrence

                         sm_o_putfield

                         write data string to occurrence

 

DESCRIPTION

 

Each of the above functions refers to data by field number and occurrence

number. As used in the above functions, occurrence means

 

  1.  item, if the field or array is scrollable;

  2.  element, if the specified field is part of a non-scrollable array; or

  3.  the specified field, if neither scrollable nor an array.

 

If the occurrence is zero, the reference is always to the current contents of

the specified field.

 

For the description of a particular function, look under the related function

without o_ in its name. For example, sm_o_amt_format is described under

sm_amt_format.


 

NAME

 

     sm_occur_no - get the occurrence number of data in the current field

 

SYNOPSIS

 

     int sm_occur_no ();

 

DESCRIPTION

 

Returns the occurrence number of the data item in the current field. If the

current field is scrollable, the occurrence number is the item ID, that is, the

item's index in the whole scroll. If the field is an element of a non-scrollable

array, the occurrence number is the field's element number. Otherwise, the

occurrence number is 1.

 

RETURNS

 

     0 if the cursor is not in a field; 1 if the cursor is in a field that is

          neither scrollable nor an array element; The element number if the

          cursor is in a non-scrollable array; The item id if the cursor is in a

          scrollable field or array.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_getcurno ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Find the number of the scrolling item under the cursor,

 * and scroll down to the next higher multiple of 5. */

 

int thisn;

 

thisn = sm_occur_no ();

sm_rscroll (sm_getcurno (), 5 - (thisn % 5));


 

NAME

 

     sm_off_gofield - move the cursor into a field, offset from the left

 

SYNOPSIS

 

     int sm_off_gofield (field_number, offset)

     int field_number, offset;

 

DESCRIPTION

 

Moves the cursor into field_number, at position offset within the field's

contents, regardless of the field's justification. The field's contents will be

shifted if necessary to bring the appropriate piece onscreen.

 

If offset is larger than the field length (or the maximum length if the field is

shiftable), the cursor will be placed in the rightmost position.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_off_gofield (field_name, element, offset);

     sm_n_off_gofield (field_name, offset);

     sm_i_off_gofield (field_name, item_id, offset);

     sm_o_off_gofield (field_number, item_id, offset);

     sm_gofield (field_number);

     sm_disp_off ();

     sm_sh_off ();

 

EXAMPLE

 

#include "smdefs.h"

#include <ctype.h>

 

/* Place the cursor over the first embedded blank in the

 * "names" field. */

 

char buf[256], *p;

int length;

 

length = sm_n_getfield (buf, "names");

for (p = buf; p < length; ++p)

     if (isspace (*p))

          break;

sm_n_off_gofield ("names", p - buf);


 

NAME

 

     sm_ok_options - set openkeybd options

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_ok_options (block, wrap, fld_reset,

          vert_arrow, horiz_arrow, val_opt)

     int block, wrap, fld_reset;

     int vert_arrow, horiz_arrow, val_opt;

 

DESCRIPTION

 

The six options set by this function control how the function sm_openkeybd

responds to cursor motion keys and other keyboard input.

 

The first defines the appearance of the cursor. The second determines whether

wrapping occurs on arrow keys. The third determines whether the arrow keys can

be used to enter a field in the middle. The next two options define cursor

movement in response to the arrow keys. The last determines when field

validation is performed.

 

Six arguments must be passed, even if you want default values for some of them.

Use the special value OK_NOCHANGE to leave a setting unaltered.

 

Mnemonics for setting the options are given in smdefs.h  and are listed below.

These mnemonics are also used for sm_mp_options.

 

   block:

   OK_NOBLOCK       Default. The cursor occupies one character position.

   OK_BLOCK         The cursor fills the field. (Actually, the cursor is

                    turned off and the current field made reverse video.)

 

   wrap:

   OK_NOWRAP        Default. No wrapping. The terminal beeps if an attempt is

                    made to arrow past the edge of the current form (or

                    window).

   OK_WRAP          The arrow keys wrap. Vertical arrows wrap straight from

                    bottom to top and vice versa; right arrow wraps to the

                    beginning of the next (or first) line, left arrow to the

                    end of the previous (or last) line.

 

   fld_reset:

   OK_NORESET       Default. The arrow keys can be used to enter the middle

                    of a field.

   OK_RESET         When a field is entered, the cursor always goes to the

                    first data position (allowing for justification, and

                    punctuation in digits-only fields).

   OK_ENDCHAR       Default off. When a character is typed at the last

                    position of a no-autotab field, beep the terminal instead

                    of overwriting the last character.

 

   vert_arrow (up and down arrow keys):

   OK_FREE          Default. Free cursor movement.

   OK_RESTRICT      The arrow keys will not take the cursor out of the

                    current field.

   OK_COLM          The cursor will be positioned to the closest field

                    (observing wrapping, if set) that overlaps the current

                    column.

   OK_SWATH         The cursor will be positioned to the closest field

                    (observing wrapping, if set) that overlaps the "swath"

                    containing the current field.

   OK_NXTLINE       The cursor will be positioned to the closest of those

                    fields (observing wrapping, if set) whose line is closest

                    to the current line.

   OK_NXTFLD        The cursor will be positioned to the field closest to the

                    current line and column. The calculation uses the

                    diagonal distance, assuming that the terminal has a 5 to

                    2 aspect ratio.

   OK_TAB           The arrows behave like TAB and BACKTAB, except that the

                    up-arrow goes to the end of the field instead of the

                    beginning.

 

   horiz_arrow (left and right arrow keys):

   OK_FREE          Default. Free cursor movement.

   OK_RESTRICT      The arrow keys will not take the cursor out of the

                    current field.

   OK_COLM          The cursor will be positioned to the closest field on the

                    current line.

   OK_SWATH         Same as OK_COLM.

   OK_NXTLINE       The cursor will be positioned to the closest field

                    (observing wrapping, if set) whose column is closest to

                    the current column.

   OK_NXTFLD        The cursor will be positioned to the field closest to the

                    current line and column. The calculation uses the

                    diagonal distance, assuming that the terminal has a 5 to

                    2 aspect ratio.

   OK_TAB           The arrows behave like TAB and BACKTAB, except that the

                    left-arrow goes to the end of the field instead of the

                    beginning.

 

   val_opt:

   OK_NOVALID       Default. Field validations are performed only on TAB and

                    RETURN keys.

   OK_VALID         Validations are performed whenever the field is exited

                    (by arrows, backtab, etc.)

 

If you define the SMOKOPTIONS variable in your setup file, this function will

automatically be called with the parameters you provide there.

 

RETURNS

 

     0 is returned if all the arguments are valid; -1 is returned if they are

          not. In this case, no options are affected.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_openkeybd ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Restore the default sm_openkeybd options. */

 

sm_ok_options(OK_NOBLOCK, OK_NOWRAP, OK_NORESET,

     OK_FREE, OK_NOVALID);


 

NAME

 

     sm_openkeybd - open the keyboard for data entry

 

SYNOPSIS

 

     #include "smdefs.h"

     #include "smkeys.h"

 

     int sm_openkeybd ();

 

DESCRIPTION

 

This routine calls sm_getkey to read the keyboard and translate function keys to

logical values. Ordinary keys, such as letters, numbers, and punctuation, are

entered into fields on the screen, subject to restrictions and edits defined

during screen authoring. Cursor motion keys, such as TAB, PAGE UP, and arrows,

move the cursor between data items; exiting a field causes its contents to be

validated against conditions defined during authoring. Data editing keys, such

as ERASE, INSERT, and BACKSPACE, make it easier to alter existing data. The

Author's Guide, in the section on "data entry," lists all the function keys and

describes their actions.

 

The processing of TRANSMIT, EXIT, HELP, and the cursor positioning keys is

determined by a routing table. For each key, if the EXECUTE bit is set, the

appropriate action is performed (tab, field erase, etc.) If the RETURN bit is

set, sm_openkeybd returns the key to its caller. Since the bits are examined

independently, four combinations of actions are possible. The default setting is

EXECUTE only (although normal execution may cause the key to be returned, as in

the case of the EXIT key).

 

You may change key actions "on the fly". For example, to disable the BACKTAB

key, the application program would execute the following:

 

     sm_route_table[BACK] = 0;

 

while to make the ERASE key return to the application program without erasing

the field's contents:

 

     sm_route_table[FERA] = RETURN;

 

The mnemonics are defined in smkeys.h . The PF, SPF, and APP function keys are

not in the routing table; they behave as though their entries were RETURN only.

A few keys, including RESCREEN and LOCAL PRINT, are processed locally in

sm_getkey and not returned to sm_openkeybd, unless their RETURN bits are set

Note that data keys may be made returnable too.

 

sm_openkeybd returns to its caller either when you press a returnable key, or

when you exit a return entry field (by completing or tabbing out). In the former

case, it returns a code for the function key. When you exit a return entry

field, it returns the field's return code, if one has been defined. If one has

not, it returns the last key struck in the field (if the field is autotab) or

the rightmost data character in the field (if it is no-autotab).

 

Another function, sm_ok_options, defines the specific behavior of certain keys

under sm_openkeybd.

 

Application programmers should be aware that JAM control strings are not

executed within this function, but at a higher level within the JAM run-time

system. If you call this function, do not expect function key control strings to

work.


 

RETURNS

 

     See above.

 

EXAMPLE

 

#include "smkeys.h"

 

/* Beep at unwanted function keys. */

int key;

 

switch (key = sm_openkeybd ())

{

     case PF1:

          save_something ();

          break;

     case PF2:

          discard_something ();

          break;

     default:

          sm_bel();

          break;

}

 

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_ok_options (block, wrap, field_reset, varrow, harrow, val_opt);


 

NAME

 

     sm_oshift - shift a field by a given amount

 

SYNOPSIS

 

     int sm_oshift (field_number, offset)

     int field_number;

     int offset;

 

DESCRIPTION

 

Shifts the contents of field_number by offset positions. If offset is negative,

the contents are shifted right (data past the left-hand edge of the field become

visible); otherwise, the contents are shifted left. Shifting indicators, if

displayed, are adjusted accordingly.

 

The field may be shifted by fewer than offset positions if the maximum shifting

width is reached thereby.

 

RETURNS

 

     The number of positions actually shifted, or 0 if the field is not found or

          is not shifting.

 

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_oshift (field_name, offset);

 

 

EXAMPLE

 

#include "smdefs.h"

 

/* Shift the Republicans gently toward the left,

 * and the Democrats toward the right.

 * For extra credit, speculate on which shift is positive. */

 

sm_n_oshift ("GOP", 1);

sm_n_oshift ("DEM", -1);


 

NAME

 

 

     sm_plcall - execute a JPL procedure

 

SYNOPSIS

 

     int sm_plcall (procedure_name)

     char *procedure_name;

 

DESCRIPTION

 

Executes the JPL procedure contained in the file procedure_name. The file will

be sought in all the directories listed in SMPATH.

 

Although JPL procedures can return values through this function, their usual use

is to modify named fields on the screen and in the LDB.

 

JPL, the JYACC Procedural Language, is the subject of a separate chapter.

 

RETURNS

 

     -1 if the procedure could not be loaded; otherwise, the value returned by

          the JPL procedure.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Imagine that you want to validate a field using a JPL

* procedure, but only on certain conditions that are awkward

* to test in JPL. You could use the following field exit

* function: */

 

int validate (field, data, occur, bits)

char *data;

{

     char *procname;

 

     if (bits & VALIDED)

          return;

     if (field_needs_validating (field, data) &&

          (procname = sm_edit_ptr (field, JPLTEXT)))

     {

          return sm_plcall (procname + 2);

     }

}


 

NAME

 

     sm_protect - protect a field completely

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_protect (field_number)

     int field_number;

 

DESCRIPTION

 

Protects the specified field from all of the following.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

To protect a field selectively, use sm_1protect; to protect an entire array, use

sm_aprotect.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_protect (field_name, element)

     sm_n_protect (field_name)

     sm_unprotect (field_number);

     sm_1protect (field_number);

     sm_aprotect (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* If the executive has a PC, unprotect a field to

 * hold its make; otherwise, protect that field. */

 

if (sm_n_is_yes ("owns_pc"))

     sm_n_unprotect ("pc_make");

else sm_n_protect ("pc_make");


 

NAME

 

     sm_putfield - put a string into a field

 

SYNOPSIS

 

     int sm_putfield (field_number, data)

     int field_number;

     char *data;

 

DESCRIPTION

 

The string data is moved into the field specified by field_number. If the string

is too long, it is truncated without warning. If it is shorter than the

destination field, it is blank filled (to the left if the field is right

justified, otherwise to the right). If data is empty or zero the field's

contents are erased; if the field is a date or time field taking system values,

the date or time is refreshed.

 

This function sets the field's MDT bit to indicate that it has been modified,

and clears its VALIDED bit to indicate that the field must be revalidated upon

exit. sm_n_putfield and sm_i_putfield will store data in the LDB if the named

field is not present in the screen. However, if the LDB item has a scope of 1

(constant), its contents will be unaltered and the function will return -1.

 

Notice that the order of arguments to this function is different from that of

arguments to the related function sm_getfield.

 

RETURNS

 

     -1 if the field is not found, 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_putfield (field_name, element, data)

     sm_i_putfield (field_name, occurrence, data)

     sm_n_putfield (field_name, data)

     sm_o_putfield (field_number, occurence)

     sm_getfield (buffer, field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Perform sm_putfield specifying a field and a string the size

 * of the field. Verify that the field matches the string

 * and that 0 is returned. */

 

sm_putfield (1, "This string has 29 characters");


 

NAME

 

     sm_putjctrl - associate a control string with a key

 

SYNOPSIS

 

     int sm_putjctrl (key, control_string, default)

     int key;

     char *control_string;

     int default;

 

DESCRIPTION

 

Each JAM screen contains a table of control strings associated with function

keys. JAM also maintains a default table of keys and control strings, which take

effect when the current screen has no control string for a function key you

press. This table enables you to define system-wide actions for keys. It is

initialized from INICTRL setup variables; see the section on setup in the

Configration Guide.

 

This function associates control_string with key in one of the tables, replacing

the control string previously associated with key (if there was one). If the

flag default is zero, the control string will be installed in the current

screen, and will disppear when you exit the screen; otherwise, it will go into

the system-wide default table.

 

If you install a default control string for a key that is defined in the current

screen, the definition in the screen will be used. Note also that JAM will not

search back up the form or window stack for function key definitions; only the

current screen and the default table are consulted.

 

Mnemonic values for key are in smkeys.h . The syntax for control strings is

defined in the Author's Guide.

 

RETURNS

 

     -5 if insufficient memory is available; 0 otherwise.

 

EXAMPLE

 

#include "smkeys.h"

 

/* These three calls duplicate the default associations for

* the JAM run-time system. */

 

sm_putjctrl (SPF1, "^jm_gotop");

sm_putjctrl (SPF2, "^jm_system");

sm_putjctrl (SPF3, "^jm_goform");


 

NAME

 

     sm_query_msg - display a question, and return a yes or no answer

 

SYNOPSIS

 

     int sm_query_msg (message)

     char *message;

 

DESCRIPTION

 

The message is displayed on the status line, until you type a yes or a no key. A

yes key is the first letter of the SM_YES entry in the message file, and a no

key is the first letter of the SM_NO entry; case is ignored. At that point, this

function returns a lower case 'y' or 'n' (English!) to its caller. All keys

other than yes and no keys are ignored.

 

The initial attribute for the message defaults to highlighted reverse video; you

may alter it by calling sm_ch_qmsgatt. Refer to sm_d_msg_line for an explanation

of how to embed changed attributes and function key names in your message. The

old status line is redisplayed as soon as you answer the question.

 

RETURNS

 

     Lower-case ASCII 'y' or 'n', according to the response.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_msg_line (message, attribute);

     sm_is_yes (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Ask a couple of straightforward questions. Be careful of

 * the dangling else, which has ruined many relationships. */

 

if (sm_query_msg("Are you single?") == 'y')

     if (sm_query_msg("Will you go out with me?") == 'y')

          if (sm_query_msg("Do you like Clint Eastwood movies?") == 'n')

               ...


 

NAME

 

     sm_qui_msg - display a message preceded by a constant tag, and reset

                  the message line

 

SYNOPSIS

 

     void sm_qui_msg (message)

     char *message;

 

DESCRIPTION

 

This function prepends a tag (normally "ERROR:") to message, and displays the

whole on the status line (or in a window if it is too long). The tag may be

altered by changing the SM_ERROR entry in the message file. The message remains

visible until the operator presses a key; refer to sm_er_options for an exact

description of error message acknowledgement. If the message is longer than the

status line, it will be displayed in a window instead.

 

This function is identical to sm_quiet_err, except that it does not turn the

cursor on. It is similar to sm_emsg, which does not prepend a tag.

 

Several percent escapes provide control over the content and presentation of

status messages. They are interpreted by sm_d_msg_line, which is eventually

called by everything that puts text on the status line (including field status

text). The character following the percent sign must be in upper-case; this is

to avoid conflict with the percent escapes used by printf and its variants.

Certain percent escapes (%W, for instance; see below) must appear at the

beginning of the message, i.e. before anything except perhaps another percent

escape.

 

   .

      If a string of the form %Annnn appears anywhere in the message, the

      hexadecimal number nnnn is interpreted as a display attribute to be

      applied to the remainder of the message. The table below gives the

      numeric values of the logical display attributes you will need to

      construct embedded attributes. If you want a digit to appear

      immediately after the attribute change, pad the attribute to 4 digits

      with leading zeroes; if the following character is not a legal hex

      digit, leading zeroes are unnecessary.

   .

      If a string of the form %KKEYNAME appears anywhere in the message,

      KEYNAME is interpreted as a logical key mnemonic, and the whole

      expression is replaced with the key label string defined for that key

      in the key translation file. If there is no label, the %K is stripped

      out and the mnemonic remains. Key mnemonics are defined in smkeys.h ;

      it is of course the name, not the number, that you want here. The

      mnemonic must be in upper-case.

   .

      If %N appears anywhere in the message, the latter will be presented in

      a pop-up window rather than on the status line, and all occurrences of

      %N will be replaced by newlines.

   .

      If the message begins with a %B, JAM will beep the terminal (using

      sm_bel) before issuing the message.

   .

      If the message begins with %W, it will be presented in a pop-up window

      instead of on the status line. The window will appear near the bottom

      center of the screen, unless it would obscure the current field by so

      doing; in that case, it will appear near the top.  If the message

      begins with %MU or %MD, and is passed to one of the error message

      display functions, JAM will ignore the default error message

      acknowledgement flag and process (for %MU) or discard (for %MD) the

      next character typed.

Note that, if a message containing percent escapes - that is, %A, %B, %K, %N or

%W - is displayed before sm_initcrt or after %W is called, the percent escapes

will show up in it.

 

            Attribute               Hex value

 

          BLACK               0 BLUE

                              1 GREEN

                              2 CYAN

                              3 RED

                              4 MAGENTA

                              5 YELLOW

                              6 WHITE

                              7

 

          B_BLACK             0 B_BLUE

                              100 B_GREEN

                              200 B_CYAN

                              300 B_RED

                              400 B_MAGENTA

                              500 B_YELLOW

                              600 B_WHITE

                              700

 

          BLANK               8 REVERSE

                              10 UNDERLN

                              20 BLINK

                              40 HILIGHT

                              80 DIM

                              1000

 

If the cursor position display has been turned on (see sm_c_vis), the end of the

status line will contain the cursor's current row and column. If the message

text would overlap that area of the status line, it will be displayed in a

window instead.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_er_options (key, discard);

     sm_emsg (message);

     sm_err_reset (message);

     sm_quiet_err (message);

     sm_await_space (message);

 

EXAMPLE

 

#include "smdefs.h"

 

sm_qui_msg ("Be %A17veewwwwy%A7 quiet. I'm hunting wabbits.");


 

NAME

 

     sm_quiet_err - display error message preceded by a constant tag, and

                    reset the status line

 

SYNOPSIS

 

     void sm_quiet_err (message)

     char *message;

 

DESCRIPTION

 

This function prepends a tag (normally "ERROR") to message, turns the cursor on,

and displays the whole message on the status line (or in a window if it is too

long). The tag may be altered by changing the SM_ERROR entry in the message

file. The message remains visible until the operator presses a key; refer to

sm_er_options for an exact description of error message acknowledgement. If the

message is longer than the status line, it will be displayed in a window

instead.

 

This function is identical to sm_qui_msg, except that it turns the cursor on. It

is similar to sm_err_reset, which does not prepend a tag. Refer to sm_d_msg_line

for an explanation of how to change display attributes and insert function key

names within a message.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_er_options (key, discard);

     sm_emsg (message);

     sm_err_reset (message);

     sm_qui_msg (message);

     sm_await_space (message);

 

EXAMPLE

 

/* Display an error message that is surely long

 * enough to be put into a window. */

 

char *buf;

 

if ((buf = malloc (8192)) == 0)

{

     sm_quiet_err ("Sorry, guy, I'm %A0017all%A7 out of memory. Here's \

500 bucks, why don't you just run down to the corner dealer and \

pick me up a meg?");

     sm_cancel ();

}


 

NAME

 

     sm_r_at_cur - display a window at the current cursor position

 

SYNOPSIS

 

     int sm_r_at_cur (screen_name)

     char *screen_name;

 

DESCRIPTION

 

Displays a window at the current cursor position, offset by one line to avoid

hiding that line's current display.

 

The named screen is sought first in the memory-resident form list, and if found

there is displayed using sm_d_window. It is next sought in all the open screen

libraries, and if found is displayed using sm_l_window. Next it is sought on

disk in the current directory; then under the path supplied to sm_initcrt; then

in all the paths in the setup variable SMPATH. If any path exceeds 80

characters, it is skipped. If the entire search fails, this function displays an

error message and returns.

 

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 if no error occurred during display of the window; -1 if the window

          cannot be successfully displayed because the format is incorrect; -2

          if the form cannot be found; -3 if the system ran out of memory but

          the screen was restored to its former state.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_form  name);

     sm_r_window (name, line, column);

     sm_close_window ();


 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* In a validation routine, if the field contains a

 * special value, open up a window to prompt for a

 * second value and save it in another field. */

 

int validate (field, data, occur, bits)

char *data;

{

     char buf[256];

 

     if (bits & VALIDED)

          return 0;

 

     if (strcmp(data, "other") == 0)

     {

          sm_r_at_cur ("getsecval");

          if (sm_openkeybd () != EXIT)

               sm_getfield (buf, 1);

          else buf[0] = 0;

          sm_close_window ();

          sm_n_putfield ("secval", buf);

     }

 

     return 0;

}


 

NAME

 

     sm_r_form - display a screen as a form

 

SYNOPSIS

 

     int sm_r_form (screen_name)

     char *screen_name;

 

DESCRIPTION

 

This function displays the named screen as a base form.

 

Bringing up a screen as a form causes the previously displayed form and windows

to be discarded, and their memory freed. The new screen is displayed with its

upper left-hand corner at the extreme upper left of the display (position (0,

0)). Any error in this function leaves the display and JAM internals in an

undefined state.

 

If the form contains display data that are too big for the physical display,

they are truncated without warning. However, if there are fields that won't fit

within the physical display, this function returns an error without displaying

the form.

 

The named screen is sought first in the memory-resident form list, and if found

there is displayed using sm_d_window. It is next sought in all the open screen

libraries, and if found is displayed using sm_l_window. Next it is sought on

disk in the current directory; then under the path supplied to sm_initcrt; then

in all the paths in the setup variable SMPATH. If any path exceeds 80

characters, it is skipped. If the entire search fails, this function displays an

error message and returns.

 

 

In the case of a return of -1 or -2, the previously displayed form is still

displayed and may be used. Other negative return code indicate that the display

is undefined; the caller should display another form before using screen manager

functions. The return code -2 typically means that the named screen does not

exist; however, it may occur because the maximum allowable number of files is

already open.

 

This function should be called by JAM applications only under unusual

circumstances, as it does not update the control stack. You should execute a

control string to display the form instead.

 

RETURNS

 

     0 if no error occurred; -1 if the screen file's format is incorrect; -2 if

          the form cannot be found; -4 if, after the screen has been cleared,

          the form cannot be successfully displayed because of a read error; -5

          if, after the screen was cleared, the system ran out of memory; -7 if

          the screen was larger than the physical display, and there were fields

          that would have fallen outside the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_at_cur (name);

     sm_r_window (name, line, column);


 

EXAMPLE

 

#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_query_msg ("Do you want to continue?") == 'y')

          longjmp (re_init);

     else sm_cancel ();

}


 

NAME

 

     sm_r_window - display a window at a given position

 

SYNOPSIS

 

     int sm_r_window (screen_name, start_line,

         start_column)

     char *screen_name;

     int start_line, start_column;

 

DESCRIPTION

 

Displays screen_name with its upper left-hand corner at the specified line and

column. The line and column are counted from zero: if start_line is 1, the form

is displayed starting at the second line of the screen.)

 

Whatever part of the display the new window does not occupy will remain visible.

However, only the top most window and its fields are accessible to keyboard

entry and library routines. JAM will not allow the cursor outside the top most,

or current, window. (See sm_wselect for a way to shuffle windows.)

 

If the window will not fit on the display at the location you request, JAM will

adjust its starting position. If the window would hang below the screen and you

have placed its upper left-hand corner in the top half of the display, the

window is simply moved up; but if your starting position is in the bottom half

of the screen, the lower left hand corner of the window is placed there. Similar

adjustments are made in the horizontal direction.

 

If, after adjustment, the window contains display data that won't fit on the

display, it is brought up anyway, without the extra. But if any field won't fit,

display of the window is aborted and an error code returned.

 

JAM provides the control string mechanism for opening, closing, and keeping

track of windows. If your code calls this function instead of executing a window

control string, certain features of the JAM run-time system will not work as

expected, particularly the EXIT key.

 

 

RETURNS

 

     0 if no error occurred during display of the screen; -1 if the screen

          file's format is incorrect; -2 if the form cannot be found; -3 if the

          system ran out of memory but the previous screen was restored; -7 if

          the screen was larger than the physical display, and there were fields

          that would have fallen outside the display.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_r_at_cur (name);

     sm_r_form (name);

     sm_close_window ();


 

EXAMPLE

 

#include "smdefs.h"

 

/* The following is a horribly inefficient (but simple) hack

 * to bring a window up centered on the display. It reads

 * the thing in once to find out how big it is (with display

 * turned off), then reads it in again in the right place.

 */

 

int center_win (window)

char *window;

{

     int start_line, start_column;

 

     sm_do_not_display = 1;

     if (sm_r_at_cur (window))

          return -1;

     /* Compute offsets. */

     start_line = (sm_nlines - (sm_eline - sm_stline)) / 2;

     start_column = (sm_ncolms - (sm_ecolm - sm_stcolm)) / 2;

     sm_close_window ();

 

     sm_do_not_display = 0;

     return sm_r_window (window, start_line, start_column);

}


 

NAME

 

     sm_rd_part - read part of a data structure to the screen

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_rd_part (screen_struct, first_field, last_field, language)

     char *screen_struct;

     int first_field, last_field, language;

 

DESCRIPTION

 

This function copies a data structure in memory to the screen, for all fields

between first_field and last_field. An array and its scrolling items will be

copied only if the first element falls between first_field and last_field.

 

The address of the structure is in screen_struct; note that this is a structure

for the whole screen, not just the part of interest. There is a utility, JYACC

f2struct, that will automatically generate such a structure from the screen

file.

 

The argument language stands for the programming language in which the structure

is defined; it controls the conversion of string and numeric data.  Zero stands

for C with null-terminated strings, one for C with blank-filled strings.

 

The structure being read may have been filled in previously by a call to

sm_wrtstruct or sm_wrt_part, using the same values of screen_structure and

language; or your application can fill it in. Using an uninitialized structure,

using an inconsistent value for language, or not terminating strings properly

can cause sm_rdstruct to lie or crash.

 

If your screen is so designed that (for instance) the input and output fields

are grouped together, this function can be much faster than sm_rdstruct, which

copies every field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wrt_part (screen_structure, first_field, last_field, language);

     sm_rdstruct (screen_structure, byte_count, language);

 

EXAMPLE

Refer to sm_wrt_part for a rather lengthy example.


 

NAME

 

     sm_rdstruct - copy data from a structure to the screen

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_rdstruct (screen_struct, byte_count,

          language)

     char *screen_struct;

     int *byte_count;

     int language;

 

DESCRIPTION

 

This function copies a data structure in memory to the screen, converting

individual items as appropriate.

 

The address of the structure is in screen_struct. There is a utility, JYACC

f2struct, that will automatically generate such a structure from the screen

file.

 

The argument byte_count is the address of an integer variable. sm_rdstruct will

store there the number of bytes copied from the structure.

 

The argument language stands for the programming language in which the structure

is defined; it controls the conversion of string and numeric data. Zero stands

for C with null-terminated strings, one for C with blank-filled strings.

 

The structure being read may have been filled in previously by a call to

sm_wrtstruct, using the same values of screen_structure and language; or your

application can fill it in. Using a partially uninitialized structure, using an

inconsistent value for language, or not terminating strings properly can cause

sm_rdstruct to lie or crash.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wrtstruct (screen_structure, byte_count, language);

     sm_rd_part (screen_structure, first_field, last_field, language);

 

EXAMPLE

Please refer to sm_wrtstruct for an extended example.


 

NAME

 

     sm_rescreen - refresh the data displayed on the screen

 

SYNOPSIS

 

     void sm_rescreen ();

 

DESCRIPTION

 

Repaints the entire display from JAM's internal screen and attribute buffers.

Anything written to the screen by means other than JAM library functions wil be

erased. This function is normally bound to the RESCREEN key and executed

automatically within sm_getkey.

 

You may need to use this function after doing screen I/O with the flag

sm_do_not_display turned on, or after escaping from an JAM application to

another program (see sm_leave). If all you want is to force writes to the

display, use sm_flush.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_flush ();

     sm_return ();

 

EXAMPLE

 

/* Mess the screen up good and proper, then restore it

 * with a call to sm_rescreen. */

 

for (i=1; i<30; i++)

{

     printf("*****************************************");

     printf("*****************************************\n");

}

 

sm_rescreen();

sm_err_reset("Verify that the screen has been restored.");


 

NAME

 

     sm_resetcrt - reset the terminal to operating system default state

 

SYNOPSIS

 

     void sm_resetcrt ();

 

DESCRIPTION

 

This function resets terminal characteristics to the operating system's normal

state. This function should be called when leaving the screen manager

environment, as before program exit.

 

It frees all the memory associated with the display and open screens. However,

the buffers holding the message file, key translation file, etc. are not

released; a subsequent call to sm_initcrt will find them in place. It then

clears the screen and turns on the cursor, transmits the RESET sequence defined

in the video file, and resets the operating system channel.

 

This function is called automatically during JAM exit, and should not be called

by application programs except in case of abnormal termination.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_leave ();

     sm_cancel ();

 

EXAMPLE

 

/* If an effort to read the first form results in

 * failure, clean up the screen and leave. */

 

if (sm_r_form ("first") < 0)

{

     sm_resetcrt ();

     exit (1);

}


 

NAME

 

 

     sm_resize - dynamically change the size of the display

 

SYNOPSIS

 

     int sm_resize (rows, columns)

     int rows;

     int columns;

 

DESCRIPTION

 

This function enables you to change the size of the display used by JAM from the

default defined by the LINES and COLMS entries in the video file. It makes it

possible to use a single video file in a windowing environment, with FORMAKER

applications being run in different sized windows; each application can set its

display size at run time. It can also be used for switching between normal and

compressed modes (e.g. 80 and 132 columns on VT100-compatible terminals).

 

All screens brought up following a call to sm_resize must fit within the display

rectangle it defines; if that rectangle is larger than the physical display, the

results will be unpredictable. You may specify at most 255 rows or columns.

 

This function clears the physical and logical screens; any displayed forms or

windows, together with data entered on them, are lost.

 

RETURNS

 

     -1 if a parameter was less than 0 or greater than 255; 0 if successful.

          Program exit on memory allocation failure. -2 if the current form or

          window exceeds the size specified for it.

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

#include "smvideo.h"

#define WIDTH_TOGGLE PF9

 

/* Somewhat irregular code to switch a VT-100 between

 * 80- and 132-column mode by pressing PF9. */

 

switch (sm_openkeybd ())

{

...

case WIDTH_TOGGLE:

     if (sm_video[V_COLMS] == 80)

     {

          printf ("\033[?3h");

          sm_resize (sm_video[V_LINES], 132);

     }

     else

     {

          printf ("\033[?3l");

          sm_resize (sm_video[V_LINES], 80);

     }

     break;

...

}


 

NAME

 

     sm_restore_data - restore previously saved data to the screen

 

SYNOPSIS

 

     int sm_restore_data (buffer)

     char *buffer;

 

DESCRIPTION

 

Restores all data items, both onscreen and offscreen, to the current screen from

an area initialized by sm_save_data. Buffer is the address of the area. Passing

an address not returned by sm_save_data, or attempting to restore to a screen

other than the one saved, can produce unpredictable results.

 

Data items are stored in the save-data buffer as null-terminated character

strings. The contents of a scrollable field or array is preceded by 2 bytes

giving the total number of items saved (high order byte first); each item is

preceded by two bytes of display attribute, and followed by a null. There is an

additional null following all the scrolling data. The whole area is preceded by

an unsigned integer giving its size. If you are programming in C, you can access

it by

 

     length = ((unsigned int *)buffer)[-1];

 

RETURNS

 

     -1 if an error occurred, usually memory allocation failure; 0 otherwise.


 

NAME

 

     sm_return - prepare for return to JAM application

 

SYNOPSIS

 

     void sm_return ();

 

DESCRIPTION

 

This routine should be called upon returning to a JAM application after a

temporary exit.

 

It sets up the operating system channel and initializes the display using the

SETUP string from the video file. It does not restore the screen to the state it

was in before sm_leave was called; use sm_rescreen to accomplish that, if

desired.

 

VARIANTS AND RELATED FUNCTIONS

 

     #include "smdefs.h"

 

     sm_leave ();

     sm_resetcrt ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Escape to the UNIX shell for a directory listing */

 

sm_leave ();

system ("ls -l");

sm_return ();

sm_c_off ();

sm_d_msg_line ("Hit any key to continue", BLINK | WHITE);

sm_getkey ();

sm_d_msg_line ("", WHITE);

sm_rescreen ();


 

NAME

 

 

     sm_rmformlist - empty out the memory-resident form list

 

SYNOPSIS

 

     void sm_rmformlist ();

 

DESCRIPTION

 

This function erases the memory-resident form list established by sm_formlist,

and releases the memory used to hold it. It does not release any of the

memory-resident screens themselves. Calling this function will prevent

sm_r_window and related functions from finding memory-resident screens.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_formlist (ptr_to_form_list);

 

EXAMPLE

 

/* Hide all the memory-resident forms, perhaps

 * because the disk versions are being modified. */

 

sm_rmformlist ();


 

NAME

 

     sm_rrecord - read data from a structure to the screen or local data

                  block

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_rrecord (structure_ptr, record_name, byte_count, lang);

     char *structure_ptr;

     char * record_name;

     int *byte_count;

     int lang;

 

DESCRIPTION

 

When a data dictionary containing records is run through the dd2struct utility,

structure definitions based on the fields of each record in the data dictionary

are saved in a file with the record name plus a language-specific extension.

Including this file in an application allows declarations of objects of these

structure types. Such objects must be declared for sm_rrecord and sm_wrecord to

be used.

 

The argument structure_ptr is the address of one such declared structure. The

argument record_name is the name of the data dictionary record, needed for

looking up its attributes.

 

The argument byte_count is a pointer to an integer. Upon return from sm_rrecord,

the value contained in the integer will be the number of bytes or characters

read from or written to the structure. It will be 0 if an error occured.

 

The argument lang is the language number, as defined in smdefs.h . Zero stands

for C with null-terminated strings, one for C with blank-filled strings.

 

sm_rrecord reads a structure into fields on the screen, or, if the field is not

on the screen, of the local data block. The fields involved are those contained

in the corresponding data dictionary record. If a structure element is of a

numeric type, such as integer or floating point, it is first converted into a

character array. Because the field names are available in the data dictionary

record definition, they may be selected arbitrarily; with sm_rdstruct, on the

other hand, the structure must contain the entire screen.

 

The structure being read should have been filled in previously by a call to

sm_wrecord, using the same values of structure_ptr, record_ptr, and lang. Or,

the application can access the elements of the structure directly, and fill in

data prior to a call of sm_rrecord. Failure to use the same values of

structure_ptr and lang, or not terminating strings properly when accessing the

structure directly, may cause sm_rrecord to lie or crash.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wrecord (structure_ptr. record_name, byte_count, lang);


 

NAME

 

 

     sm_rs_data - restore saved data to some of the screen

 

SYNOPSIS

 

     void sm_rs_data (first_field, last_field, buffer);

     int first_field;

     int last_field;

     char *buffer;

 

DESCRIPTION

 

Restores all data items, both onscreen and offscreen, to the fields between

first_field and last_field from an area initialized by sm_sv_data. The address

of the area is in buffer.

 

See sm_sv_data to create a buffer for subsequent retrieval by this function. If

the range of fields passed to this function does not match that passed to

sm_sv_data, or buffer is not a value returned by that function, grievous errors

will probably occur.

 

The format of the data area is explained briefly under sm_restore_data.

 

RETURNS

 

     -1 if an error occurred, usually memory allocation failure; 0 otherwise.

 

EXAMPLE


 

NAME

 

     sm_rscroll - scroll an array or parallel arrays

 

SYNOPSIS

 

     int sm_rscroll (field_number, req_scroll)

     int field_number;

     int req_scroll;

 

DESCRIPTION

 

This function scrolls an array or set of parallel arrays by req_scroll items. If

req_scroll is positive, the array scrolls down (towards the bottom of the data);

otherwise, it scrolls up. It supersedes the Release 3 function sm_scroll.

 

The function returns the actual amount scrolled. This could be the amount

requested; a smaller value, if the requested amount would bring the array past

its beginning or end; or zero, if the array was at its beginning or end, or an

error occurred. It is never negative.

 

RETURNS

 

     See above.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_rscroll (field_name, req_scroll);

     sm_t_scroll (field_number);

     sm_ascroll (field_number, occurrence);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Find the number of the scrolling item under the cursor,

 * and scroll down to the next higher multiple of 5. */

 

int thisn;

 

thisn = sm_occur_no ();

sm_rscroll (sm_getcurno (), 5 - (thisn % 5));


 

NAME

 

     sm_s_val - validate the current screen

 

SYNOPSIS

 

     int sm_s_val ();

 

DESCRIPTION

 

This function loops through the screen validating each field and data item,

whether on or offscreen, that is not protected from validation (VPROTECT). It is

called automatically from sm_openkeybd when you press the TRANSMIT key.

 

Validations are performed as follows. If there are no scrolling arrays or

fields, the order is left to right, then top to bottom. If a scrolling array or

field is encountered, and it contains the first onscreen item for that array (or

field), earlier offscreen items are validated first. If it contains the last

onscreen item, any later offscreen items are validated immediately after that

field.

 

If parallel scrolling arrays (or fields) exist, there are more complications.

When an offscreen item is validated, the corresponding items from parallel

arrays are validated as well, from left to right. The offscreen items preceding

the parallel arrays are validated before the first onscreen item of the leftmost

of the parallel arrays; similarly, the offscreen items following the arrays are

validated immediately after the last onscreen item of the rightmost.

 

Individual field validations are performed in the following order. The table

also notes conditions under which validations are skipped.

 

              Validation         Skip if valid       Skip if empty

 

        required           y            n

        must fill          y            y

        regular expression y            y

        range              y            y

        check-digit        y            y

        date or time       y            y

        table lookup       y            y

        currency format    y            n*

        math expresssion   n            n

        exit function      n            n

        jpl function       n            n

 

*

 The currency format edit contains a skip-if-empty flag; see the Author's Guide.

 

If you need to force a skip-if-empty validation, make the field required. A

digits-only field must contain at least one digit in order to be considered

nonempty; for other character edits, any nonblank character makes the field

nonempty. The currency format edit contains a skip-if-empty flag; see the

Author's Guide.

 

If an item fails validation, the cursor is positioned to it and an error message

displayed. (If the item was offscreen, its array or field is first scrolled to

bring it onscreen.) This routine returns at the first error; fields past that

will not be validated.

 

RETURNS

 

     -1 if any field fails validation, 0 otherwise.


 

VARIANTS AND RELATED FUNCTIONS

 

     sm_fval (field_number);

 

EXAMPLE

 

#include "smdefs.h"

#include "smkeys.h"

 

/* Treat the SPF1 key as transmit, for a change. */

 

int key;

 

sm_d_msg_line ("Press %KSPF1 when done.", WHITE | REVERSE);

 

while ((key = sm_openkeybd ()) != EXIT)

{

     if (key == SPF1)

     {

          if (sm_s_val ())

               sm_err_reset ("Please correct the mistake(s).");

          else break;

     }

}

...


 

NAME

 

     sm_save_data - save screen contents

 

SYNOPSIS

 

     char *sm_save_data ();

 

DESCRIPTION

 

The current screen's data is saved for external access or subsequent retrieval,

and the address of the save area returned.

 

To restore the saved data, use sm_restore_data; refer to that function for a

brief explanation of the save format. Use sm_sv_free to discard a save area.

 

RETURNS

 

     0 if insufficient memory was available, otherwise the address of a memory

          area containing the screen's data.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_restore_data (buffer);

     sm_sv_data (first_field, last_field);

     sm_sv_free (buffer);

 

EXAMPLE


 

NAME

 

     sm_sc_max - alter the maximum number of items allowed in a scrollable

                 field or array

 

SYNOPSIS

 

     int sm_sc_max (field_number, new_max)

     int field_number, new_max;

 

DESCRIPTION

 

Changes the maximum number of items allowed in field_number, and in all fields

(or arrays) parallel to it. The original maximum is set when the form is

created. If the desired new maximum is less than the number of items already

entered into the field or array, the old maximum will remain. The maximum can

decrease only if new_max is between the number of items already entered and the

previous maximum.

 

RETURNS

 

     The actual new maximum (see above); or 0 if the desired maximum is invalid,

          or if the field is not scrollable.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_sc_max (field_name, new_max);

     sm_max_item (field_number);

     sm_num_items (field_number);

 

EXAMPLE

 

#include "smdefs.h"

#define SCROLLNUM 7

 

/* When the number of items entered in a scroll exceeds

 * ten less than the maximum, increase the maximum by 100. */

 

int maxnow;

 

maxnow = sm_max_item (SCROLLNUM);

if (maxnow - sm_num_items (SCROLLNUM) < 10)

     sm_sc_max (SCROLLNUM, maxnow + 100);


 

NAME

 

     sm_sdate - get formatted system date

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_sdate (format)

     char *format;

 

DESCRIPTION

 

Obtains the current date from the operating system, and formats it according to

format, and returns the resulting string.

 

You may retrieve the date format from a field, using sm_edit_ptr, or construct

it by other means. Refer to the Author's Guide for a description of date

formats. Refer to sm_calc for a way of getting an arbitrary date into a

formatted date field.

 

This function shares a single static buffer with other date and time formatting

functions. The formatted date returned by this function should therefore be

processed quickly, or copied to a local string.

 

RETURNS

 

     The current date in the specified format. Empty if the format is invalid.

 

EXAMPLE

 

#define FORMAT1 "MM/DD/YY"

 

/* Display the date and the string used to format it. */

 

     sm_n_putfield ("format", FORMAT1);

     sm_n_putfield ("date", sm_sdate (FORMAT1));


 

NAME

 

     sm_setbkstat - set background text for status line

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_setbkstat (message, attr)

     char *message;

     int attr;

 

DESCRIPTION

 

The message is saved, to be shown on the status line whenever there is no higher

priority message to be displayed. The highest priority messages are those passed

to sm_d_msg_line, sm_err_reset, sm_quiet_err, or sm_query_msg; the next highest

are those attached to a field by means of the status text option (see the JAM

Author's Guide). Background status text has lowest priority.

 

Attr is the initial display attribute for the message, and is a combination of

the following values.

 

                 Colors                    Highlights

 

        BLACK     BLUE       BLANK     REVERSE

        GREEN     CYAN       UNDERLN   BLINK

        RED       MAGENTA    HILIGHT

        YELLOW    WHITE      DIM

 

The background colors defined in smdefs.h  (B_BLACK and so forth) are also

available.

 

sm_setstatus sets the background status to an alternating ready/wait flag; you

should turn that feature off before using this function.

 

Refer to sm_d_msg_line for an explanation of how to embed attribute changes and

function key names into your message.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_setstatus (flag);

     sm_d_msg_line (message, attribute);

 

EXAMPLE

 

#include "smdefs.h"

#define PAUSE sleep (3)

 

/* The hierarchy of status messages. Assume the field

 * "mama" has status text reading "Mama bear", and that

 * the home field has none. */

 

sm_d_msg_line ("", WHITE);

sm_setstatus (0);

sm_setbkstat ("Baby bear", MAGENTA);

PAUSE;

sm_n_gofield ("mama");

PAUSE;

sm_d_msg_line ("Papa bear", BLUE | HILIGHT);

PAUSE;

sm_home ();

PAUSE;


 

NAME

 

     sm_setstatus - turn alternating background status message on or off

 

SYNOPSIS

 

     void sm_setstatus (mode)

     int mode;

 

DESCRIPTION

 

If mode is non-zero, alternating status flags are turned on. After this call,

one message (normally Ready) is displayed on the status line while the keyboard

is open for input, and another (normally Wait) when it is not. If mode is zero,

the messages are turned off.

 

The status flags will be replaced temporarily by messages passed to sm_err_reset

or a related function. They will overwrite messages posted with sm_d_msg_line or

sm_setbkstat.

 

The alternating messages are stored in the message file as SM_READY and SM_WAIT,

and can be changed there. Attribute changes and function key names can be

embedded in the messages; refer to sm_d_msg_line for instructions.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_setbkstat (message, attr);

 

EXAMPLE

 

#include "smdefs.h"

#include "smerror.h"

#define PAUSE sleep (3)

 

char buf[100];

 

/* Tell people what you're gonna tell 'em. */

sprintf (buf, "You will soon see %s alternating with %s below.",

     sm_msg_get (SM_READY), sm_msg_get (SM_WAIT));

sm_do_region (3, 0, 80, WHITE, buf);

 

/* Now tell 'em. */

sm_setstatus (1);

PAUSE;               /* Shows WAIT */

sm_openkeybd ();     /* Shows READY */

 

/* Finally, tell 'em what you told 'em. */

sprintf (buf, "That was %s alternating with %s on the status line.",

     sm_msg_get (SM_READY), sm_msg_get (SM_WAIT));

sm_err_reset (buf);


 

NAME

 

     sm_sh_off - determine the cursor location relative to the start of a

                 shifting field

 

SYNOPSIS

 

     int sm_sh_off ();

 

DESCRIPTION

 

Returns the difference between the start of data in a shiftable field and the

current cursor location. If the current field is not shiftable, it returns the

difference between the leftmost column of the field and the current cursor

location, like sm_disp_off.

 

RETURNS

 

     The difference between the current cursor position and the start of

          shiftable data in the current field. -1 if the cursor is not in a

          field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_disp_off ();

 

EXAMPLE

 

#include "smdefs.h"

 

/* Fancy test to see whether a field is shifted to the left. */

 

if (sm_sh_off () != sm_disp_off ())

     sm_err_reset ("Ha! You shifted!");


 

NAME

 

     sm_size_of_array - get the number of elements in an array

 

SYNOPSIS

 

     int sm_size_of_array (field_number)

     int field_number;

 

DESCRIPTION

 

Returns the number of elements in the array containing field_number. A non-array

field is considered to have one element.

 

RETURNS

 

     0 if the field designation is invalid; 1 if the field is not an array; The

          number of elements in the array otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_n_size_of_array (field_name);

     sm_num_items (field_number);

     sm_max_occur (field_number);

 

EXAMPLE

 

#define THEFIELD 6

 

/* Compute the number of pages of data in a scrolling

 * array, where a page is one onscreen-array-full. */

 

int pages, elements;

 

elements = sm_size_of_array (THEFIELD);

pages = (sm_num_items (THEFIELD) + elements - 1) / elements;


 

NAME

 

 

     sm_smsetup - initalize table of setup variables, and execute some

 

SYNOPSIS

 

     int sm_smsetup (memfile)

     char memfile[];

 

DESCRIPTION

 

This function loads a file or files of setup variables into memory, and uses

some of them to set various screen manager options. It is called automatically

at screen manager start-up, by sm_initcrt. The file can be either disk- or

memory-resident. A complete list of setup variables can be found in the section

on the setup file, in the Configuration Guide. You may find using a setup file

to be more flexible and convenient than calling many of the option-setting

routines in the library.

 

If the argument memfile is nonzero, this function uses it alone, in place of the

system SMVARS file. If there is an SMSETUP in the memory-resident file or the

system environment, it will be used too. If memfile is zero, the two files

pointed to by SMVARS and SMSETUP are read in.

 

There is another function, sm_unsetup, that restores all the options affected by

this routine to their default values.

 

RETURNS

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_unsetup ();

 

EXAMPLE

 

/* Install a memory-resident setup file. */

extern char memsetup[];

 

if (sm_smsetup (memsetup) < 0)

     sm_cancel ();


 

NAME

 

     sm_stime - get formatted system time

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_stime (format)

     char *format;

 

DESCRIPTION

 

Obtains the current time from the operating system, formats it according to

format, and returns the resulting string. The format can be obtained from a time

field by calling sm_edit_ptr, or you can construct it by other means.

 

See the Author's Guide for a description of recognized time formats.

 

This function shares a single static buffer with other date and time formatting

functions. The formatted time returned by this function should therefore be

processed quickly, or copied to a local string.

 

RETURNS

 

     The time of day in the specified format.

 

EXAMPLE

 

#define FORMAT1 " HH:MM:SS"

 

/* Print the time, and why it looks the way it does. */

 

     sm_n_putfield ("format" ,FORMAT1);

     sm_n_putfield ("time", sm_stime (FORMAT1));


 

NAME

 

     sm_strip_amt_ptr - strip amount editing characters from a string

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_strip_amt_ptr (field_number, inbuf)

     int field_number;

     char *inbuf;

 

DESCRIPTION

 

Strips all non-digit characters from the string, except for an optional leading

minus sign and decimal point. If inbuf is nonzero, field_number is ignored and

the passed string is processed in place.

 

If inbuf is zero, the contents of field_number are used. This function shares

with several others a pool of buffers where it stores returned data. The value

returned by any of them should therefore be processed quickly or copied.

 

RETURNS

 

     A pointer to a buffer containing the stripped text, or 0 if inbuf is 0 and

          the field number is invalid.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_dblval (field_number);

     sm_amt_format (field_number, string);

 

EXAMPLE

 

#include "smdefs.h"

 

char *strip_text;

 

strip_text = sm_strip_amt_ptr (0, "$1,123,456");

if (strcmp (strip_text, "1123456") != 0)

     punt ("Bug in strip_amt_ptr");


 

NAME

 

      #COMMENT(NOT PYRCOB) sm_sv_data - save partial screen contents

 

SYNOPSIS

 

     #include "smdefs.h"

 

     char *sm_sv_data (first_field, last_field)

     int first_field;

     int last_field;

 

DESCRIPTION

 

The current form's data, from all fields numbered from first_field to

last_field, is saved for external access or subsequent retrieval, and the

address of the save area returned. Use sm_rs_data to restore it.

 

See sm_restore_data for the save format.

 

RETURNS

 

     The address of an area containing the saved data. 0 if the current screen

          has no fields, or sufficient free memory is not available.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_rs_data (first_field, last_field, buffer);

     sm_save_data ();

     sm_sv_free (buffer);


 

NAME

 

 

     sm_sv_free - free a save-data buffer

 

SYNOPSIS

 

     void sm_sv_free (buffer)

     char *buffer;

 

DESCRIPTION

 

The save area at buffer, which must have been created by sm_save_data or

sm_sv_data, is released and is no longer accessible.

 

sm_save_data and related functions record the addresses of save areas, and after

ten have been accumulated the oldest are released automatically; calls to this

function are therefore not strictly necessary.


 

NAME

 

     sm_t_scroll - test whether field can scroll

 

SYNOPSIS

 

     int sm_t_scroll (field_number)

     int field_number;

 

DESCRIPTION

 

Returns 1 if the field in question is scrollable, and 0 if not or if there is no

such field.

 

RETURNS

 

     1 if field exists and scrolls; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_t_shift (field_number);

 

EXAMPLE

 

/* If the current field is scrolling, set it back to

 * the beginning. */

 

if (sm_t_scroll (sm_getcurno ())

     sm_ascroll (sm_base_fldno (sm_getcurno ()), 1);


 

NAME

 

     sm_t_shift - test whether field can shift

 

SYNOPSIS

 

     int sm_t_shift (field_number)

     int field_number;

 

DESCRIPTION

 

Returns 1 if the field in question is shiftable, and 0 if not or if there is no

such field.

 

RETURNS

 

     1 if field is shifting. 0 if not shifting or no such field

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_t_scroll (field_number);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Turn on shifting indicators if the screen contains any

 * shifting fields. */

 

int f;

 

for (f = 1; f <= sm_numflds; ++f)

{

     if (sm_t_shift (f))

     {

          sm_ind_set (IND_SHIFT);

          sm_rescreen ();

          break;

     }

}


 

NAME

 

     sm_tab - move the cursor to the next unprotected field

 

SYNOPSIS

 

     void sm_tab ();

 

DESCRIPTION

 

If the cursor is in a field with a next-field edit and one of the fields

specified by the edit is unprotected, the cursor is moved to the first enterable

position of that field. Otherwise, the cursor is advanced to the first enterable

position of the next unprotected field on the form.

 

The first enterable position is the leftmost in a left-justified field and the

rightmost in a right-justified field; furthermore, in a digits-only field,

punctuation characters are skipped.

 

Unlike the TAB key, this function does not cause field exit processing to be

performed. To simulate a TAB keystroke, see below.

 

EXAMPLE

 

#include "smkeys.h"

 

/* This moves the cursor to the next field. */

sm_tab ();

 

/* This moves the cursor to the next field, validating

 * the current one first. */

sm_ungetkey (TAB);


 

NAME

 

     sm_tst_all_mdts - find first modified item

 

SYNOPSIS

 

     int sm_tst_all_mdts (occurrence)

     int *occurrence;

 

DESCRIPTION

 

This routine tests the MDT bits of all occurrences of all fields on the current

screen, and returns the field and occurrence numbers of the first item with its

MDT set, if there is one. The MDT bit indicates that an item has been modified,

either from the keyboard or by the application program, since the screen was

displayed (or since its MDT was last cleared by sm_op_mdt).

 

This function returns zero if no items have been modified. If one has been

modified, it returns the field number, and stores the occurrence number in the

variable addressed by occurrence.

 

RETURNS

 

     0 if no MDT bit is set anywhere on the screen; The number of the first

          field on the current screen for which some occurrence has its MDT bit

          set. In this case, the number of the first occurrence with MDT set is

          returned in the reference parameter occurrence.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_op_mdt (field_number, operation);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Clear MDT for all fields on the form; then write

 * data to the last field, and check that its MDT is

 * the first one set. */

 

int occurrence;

 

sm_cl_all_mdts();

sm_putfield (sm_numflds, "Hello");

if (sm_tst_all_mdts (&occurrence) != sm_numflds)

     sm_err_reset ("Something is rotten in the state of Denmark.");


 

NAME

 

 

     sm_u_async - asynchronous keyboard input hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_async;

 

     int my_async (interval)

     int interval;

 

DESCRIPTION

 

The function is called only when the keyboard is being read, and only if a

keystroke does not arrive within the time limit given at installation. That

timeout is in tenths of a second, although its real value depends on the

granularity of your system's clock; it is placed in the intrn_use member of the

fnc_data structure. See sm_install for more about installation.

 

The asynchronous function is called from sm_gtchar, one level below sm_getkey.

If it returns zero, everything proceeds as before. If it returns -1, sm_gtchar

goes directly to the keyboard for a character, and does not call the

asynchronous function again until it gets one (and is asked for another). Any

other value is passed back to sm_getkey.

 

The authoring utility uses an asynchronous function to update its cursor

position display. Another typical use might be to implement a real-time clock

display.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     See above.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_install (which_hook, what_funcs, howmany);


 

EXAMPLE

 

/* A typical use of the window selection routines is to

 * update information to a window that may (or may not) be

 * covered.  For example, suppose that the current time

 * should be maintained on the underlying form.  Assume

 * that a field named "curtime" exists on that form.

 * The following code fragments can be used

 * to maintain that field independent of the number of windows

 * currently open above the form.

 */

 

#include "smdefs.h"

 

updatetime()

{

     sm_wselect (0); /* quietly select the bottom form */

     sm_n_putfield ("curtime", ""); /* update system time display */

     sm_wdeselect ();/* restore visible window */

     sm_flush ();

     return (0);

}

 

/* In initialization code: called every second. */

 

     static struct fnc_data afunc = { 0, updatetime, 0, 10, 0, 0 };

     sm_install (ASYNC_FUNC, &afunc, (int *)0);


 

NAME

 

 

     sm_u_avail - playback character availability hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_avail;

 

     int my_avail (interval)

     int interval;

 

DESCRIPTION

 

This hook is called from sm_keyhit, q.v. That function's mission is to find if

there's a key waiting to be read; before looking at the physical keyboard, it

checks for avavilable playback characters by calling this function. The latter

should return a positive value if there are characters available for playback

(by sm_u_play), and zero if there is nothing to play back. If the playback

system is inactive, it should return -1, and sm_keyhit will go on to poll the

keyboard. This hook is also called from sm_getkey; if it returns a positive

value, the latter then calls sm_u_play to retrieve a key.

 

The argument interval is the length of time, in tenths of a second, that

sm_keyhit is supposed to wait for a key. You can use this to simulate a

realistic rate of typing, by pausing in this function.

 

Along with sm_u_play and sm_u_record, this function forms part of a keystroke

recording and playback package. Such a package can be quite useful in regression

testing and performance analysis of JAM applications, because it enables you to

reproduce a series of inputs exactly and with little effort.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     1 (or other positive value) if there are characters to be played back; 0 if

          the playback system is active but there are no characters available;

          -1 if the playback system is inactive.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_keyfilter (flag);

     sm_u_play ();

     sm_u_record (key);

 

EXAMPLE

 

See sm_u_play for a detailed example of a keystroke recording package.


 

NAME

 

 

     sm_u_ckdigit - check digit validation hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_ckdigit;

 

     int myckdigit (field, data, item, modulus, digits);

     int field, item, modulus, digits;

     char *data;

 

DESCRIPTION

 

This hook is called by field validation. It verifies that data contains the

required minimum number of digits, terminated by the proper check digit. If not,

it positions the cursor to the indicated occurrence and posts an error message

before returning. It also be used to check any character string, or any field.

If data is null, the string to check is obtained from the field and occurrence

number, and the error message is displayed if that string is bad. If

field_number is zero, no message will be posted, but the function's return code

will indicate whether the string passed its check.

 

The source code to sm_ckdigit is included with JAM; refer to it for descriptions

of our check digit algorithms and how to implement your own. Note that the

parameter digits specifies the minimum number of digits, not the check digit. If

you decide to modify that module without renaming it, you do not need to call

sm_install; JAM already does that.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     0 if the number contains the minimum number of digits and the proper check

          digit; -1 for a present but invalid string; -2 if no string is

          supplied and the field or occurrence number is out of range.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_ckdigit (field, data, item, modulus, digits);

     sm_install (which_hook, what_func, howmany);

 

EXAMPLE

 

#include "smdefs.h"

 

/* Validate a check digit in field 1 directly. The

 * routine itself will display an error message if the

 * validation fails. */

 

if (sm_ckdigit(1, (char *)0, 0, 10, 2))

     sm_gofield (1);


 

NAME

 

 

     sm_u_inscrsr - insert/overstrike mode switch hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_inscrsr;

 

     int myinscrsr (insert_mode)

     int insert_mode;

 

DESCRIPTION

 

The JAM library calls a user-defined function while switching from insert to

overstrike mode (or vice versa). The intention is to allow for a visible

indication of the mode. Insert_mode is 1 if JAM is entering insert mode, and 0

if it is entering overstrike mode.

 

Your function must be installed via a call to sm_install, q.v. It will be called

by sm_getkey when the latter reads the INSERT key from the keyboard. If the

INSON and INSOFF entries are present in the video file, JAM will send them in

addition to calling this function; if all you want is a change of cursor style,

you can get away with that.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_install (which_hook, what_function, howmany);

 

EXAMPLE

 

#include "smdefs.h"

 

/* The following function is installed on the "change

 * insert mode" hook. It modifies an area at the lower right-

 * hand corner of the screen to show whether the current

 * mode is insert or overstrike. */

 

int insf (insert_on)

int insert_on;

{

     if (insert_on)

          sm_do_region (sm_nlines - 1, sm_ncolms - 4, 3,

               REVERSE | WHITE, "INS");

     else

          sm_do_region (sm_nlines - 1, sm_ncolms - 4, 3,

               REVERSE | WHITE, "OVR");

     return 0;

}

 

/* Installation code for the above. */

 

struct fnc_data insf = {

     "mycurs", mycurs, 0, 0, 0, 0

};

 

sm_install (INSCRSR_FUNC, &insf, (int *)0);

NAME

 

 

     sm_u_keychg - logical key translation hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_keychg;

 

     int mykeychg (input_key)

     int input_key;

 

DESCRIPTION

 

This is a user-installable function called from sm_getkey. You can install your

own by calling sm_install with KEYCHG_FUNC.

 

The argument to this function is a logical key read by sm_getkey; you may put

special key processing here. If your function returns zero, the key is removed

from the input stream, and sm_getkey reads in the next one without returning to

its caller. If your function returns any other value, sm_getkey returns that

directly to its caller.

 

See sm_u_play for an additional example of a keychange function.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     as described above

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_install (which_hook, what_func, howmany);

     sm_getkey ();


 

EXAMPLE

 

/* What follows is an extremely simple-minded keyboard

 * macro implementation, using a keychange function.

 * Any character following a backslash \ is looked up in a

 * hard-coded table, and the string corresponding to

 * that character (if any) substituted. If the character isn't

 * there, it beeps. The expansion string is pushed back

 * onto the input using sm_ungetkey.

 */

 

#include "smdefs.h"

 

int macro ();

void try_expand ();

 

/* Macro expansion table. Will expand \j to "JYACC, Inc."

 * and so forth. The zero tag marks the end of the table. */

 

static struct macrotab {

     char tag;

     char *expansion;

} macrotab[] = {

     'j', "JYACC, Inc.",

     'v', "Version 4.0",

     'a', "116 John St., New York, NY, 10038",

     0,   ""

};

 

/* This is the keychange function. It looks out for a

 * backslash, and when it gets one sets a flag to try

 * expanding the next character it gets. Both the backslash

 * and the following character are deleted from the input

 * stream. The actual expansion is done in a subroutine.

 */

 

int macro (key)

int key;

{

#define ESCAPE '\\'

     static int saw_escape_last_time;

 

     if (saw_escape_last_time)

     {

          try_expand (key);

          saw_escape_last_time = 0;

          return 0;

     }

     else if (key == ESCAPE)

     {

          saw_escape_last_time = 1;

          return 0;

     }

     else return key;

}

 

/* This function looks up 'key' in the table, and if it

 * finds it there, pushes the expansion onto the input.

 * Note that the expansion must be pushed backwards.

 */

 

void try_expand (key)

int key;

{

     struct macrotab *m;

     char *p;

 

     for (m = macrotab; m->tag != 0; ++m)

     {

          if (m->tag == key)

          {

               p = m->expansion + strlen (m->expansion) - 1;

               while (p >= m->expansion)

                    sm_ungetkey (*p--);

               return;

          }

     }

 

     sm_bel ();     /* Could not expand */

}

 

/* Finally, here is code to install 'macro' as a

 * keychange function, using sm_install. */

 

static struct fnc_data keychg = {

     "macro", macro, 0, 0, 0, 0

};

 

sm_install (KEYCHG_FUNC, &keychg, (int *)0);


 

 

 

NAME

 

 

     sm_u_play - keystroke playback hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_play;

 

     int myplay ();

 

DESCRIPTION

 

This hook is called from sm_getkey. If it returns a nonzero value, sm_getkey

treats it as an already translated logical key, which is returned to its caller.

The key may be a standard displayable ASCII character, or one of the values

defined in smkeys.h . Normally, the returned key will have been stored in some

fashion by a previous call to sm_u_record; the recording algorithm is entirely

up to you. Refer to sm_getkey for details about just when this and other input

processing hooks are invoked.

 

Along with sm_u_avail and sm_u_record, this function forms part of a keystroke

recording and playback package. Such a package can be quite useful in regression

testing and performance analysis of JAM applications, because it enables you to

reproduce a series of inputs exactly and with little effort.

 

When sm_getkey obtains a key from this function, it does not update the display

first, as it does when reading a key from the keyboard. You may want to call

sm_flush from this function or from sm_u_avail in order to keep the display in

sync with the input, e.g. to have data characters echoed.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     Any ASCII character or JAM logical key code; zero if there is nothing to

          play back.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_keyfilter (flag);

     sm_u_record (key);

     sm_u_avail (interval);

 

EXAMPLE

 

#include "smdefs.h"

#include "smerror.h"

#include "smkeys.h"

 

/* The code below forms a simple keystroke recording and playback

 * package, using the three hooks provided for that purpose.

 * Pressing PF2 causes following keystrokes to be saved in memory;

 * pressing PF3 stops recording keystrokes; and pressing PF4 causes

 * the list of saved keystrokes to be played back, with a one-second

 * pause between them.  These transitions are done in a keychange

 * function, which is another sm_getkey hook.

 * While either recording or playback is in progress, a small

 * display area in the upper left-hand corner tells what is going on

 * and how many keys have been processed so far.

 */

 

/* Assign names for the control keys. */

#define START_RECORDING   PF2

#define STOP_RECORDING    PF3

#define START_PLAYING     PF4

 

int play(), record(), avail(), playchange();

void status();

 

int  *keylist,    /* Buffer for saved keys */

     keycount,    /* Number of keys saved up */

     keysize,     /* Size of save buffer */

     playkey,     /* Index of next key to play back */

     recording,   /* Nonzero while recording */

     playing;     /* Nonzero while playing back */

 

/* This function is installed on the playback hook.

 * It just steps through the list of recorded keys, and

 * turns itself off when it reaches the end. */

 

int play ()

{

     if (! playing)

          return 0;

     else if (playkey == keycount)

     {

          playing = 0;

          status (0, 0);

          return 0;

     }

     else

     {

          status ('P', playkey + 1);

          return keylist[playkey++];

     }

}

 

/* This function is installed on the record hook.

 * It save the key it is passed in a dynamic array,

 * expanding the array when it's full. */

 

int record (key)

{

     if (recording)

     {

          if (keycount == keysize)

               keylist = (int *)realloc(keylist,

          sizeof(int) * (keysize *= 2));

          keylist[keycount++] = key;

          status ('R', keycount);

     }

     return 0;

}

 

/* This function tells sm_getkey whether there's anything left

 * to play back. It also flushes the display and pauses for

 * a second, so you can see the replayed characters going by. */

 

int avail (interval)

{

     if (playing)

     {

          sm_flush ();

          sleep (1);

          return 1;

     }

     return 0;

}

 

/* This function controls all of the above, triggering on

 * the PF2, PF3, and PF4 keys. */

 

int playchange (key)

{

     switch (key)

     {

     case START_PLAYING:

          if (recording)

               sm_quiet_err ("You're recording.");

          else if (keycount <= 0)

               sm_quiet_err ("Nothing to play.");

          else

          {

               playing = 1;

               playkey = 0;

               status ('P', 0);

          }

          return 0;

 

     case START_RECORDING:

          if (playing)

               sm_quiet_err ("You're playing.");

          else if (recording)

               sm_quiet_err ("You're already recording.");

          else

          {

               keylist = (int *)malloc(sizeof(int) * (keysize = 50));

               keycount = 0;

               recording = 1;

               status ('R', 0);

          }

          return 0;

 

     case STOP_RECORDING:

          recording = 0;

          status (0, 0);

          return 0;

 

     default:

          return key;

     }

}

 

/* This routine places the current operation and count in the

 * upper left-hand corner of the screen. The calculation is

 * to avoid borders. */

 

void status (flag, count)

{

#define SWIDTH    4

     int  corner;

     char buf[10];

 

     corner = sm_cform->form.bord_char ? 1 : 0;

     if (flag == 0)

     {

          buf[0] = 0;

          sm_do_region (corner, corner, SWIDTH, WHITE, buf);

     }

     else

     {

          sprintf (buf, "%c%.3d", flag, count);

          sm_do_region (corner, corner, SWIDTH, REVERSE | WHITE, buf);

     }

}

 

/* Finally, here is code to initialize the necessary hooks. */

 

static struct fnc_data playf = {

     "play", play, C_FUNC, 0, 0, 0

};

static struct fnc_data recordf = {

     "record", record, C_FUNC, 0, 0, 0

};

static struct fnc_data availf = {

     "avail", avail, C_FUNC, 0, 0, 0

};

static struct fnc_data changef = {

     "playchange", playchange, C_FUNC, 0, 0, 0

};

 

sm_install (PLAY_FUNC, &playf, (int *)0);

sm_install (RECORD_FUNC, &recordf, (int *)0);

sm_install (AVAIL_FUNC, &availf, (int *)0);

sm_install (KEYCHG_FUNC, &changef, (int *)0);


 

NAME

 

 

     sm_u_record - keystroke recording hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_record;

 

     void myrecord (key);

     int key;

 

DESCRIPTION

 

This hook is called from sm_getkey. When it has a translated key value in hand,

whether read from the keyboard or obtained from another source, sm_getkey passes

it to this function so that it may be recorded, and perhaps played back by a

future call to sm_u_play. Values stored by sm_ungetkey are not passed to this

hook, but are returned directly to the caller of sm_getkey; refer to that

function's description for details about just when this and other input

processing hooks are invoked.

 

Along with sm_u_play and sm_u_avail, this function forms part of a keystroke

recording and playback package. Such a package can be quite useful in regression

testing and performance analysis of JAM applications, because it enables you to

reproduce a series of inputs exactly and with little effort.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_keyfilter (flag);

     sm_u_play ();

     sm_u_avail (interval);

 

EXAMPLE

 

See sm_u_play for a detailed example of a keystroke recording package.


 

NAME

 

 

     sm_u_statfnc - status line display hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_statfnc;

 

     int mystatfnc ();

 

DESCRIPTION

 

This function is called before the generic code JAM uses to display stuff on the

status line. It is intended for use on terminals with really weird status lines

indecipherable to the generic code (see the video manual in the Configuration

Guide), but more imaginative uses are possible.

 

This function takes no arguments. The text to be displayed on the status line is

always stored in the last line of the global screen data buffer, sm_screen. You

can examine that line as:

 

     sm_screen[sm_nlines]

 

 

and have your way with it. If your function returns 0, sm_d_msg_line continues

with its processing. Otherwise, sm_d_msg_line returns immediately, assuming that

you have updated the status line.

 

jxform uses this hook to redisplay the cursor position on the screen whenever

the status line is changed; see sm_c_vis. Your function must be installed by a

call to sm_install, using STAT_FUNC.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     See above.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_d_msg_line (message, attribtue);

     sm_c_vis (flag);

     sm_install (which_hook, what_func, howmany);

 

EXAMPLE


 

NAME

 

 

     sm_u_uinit - do application-specific things at screen manager

                  initialization time

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_uinit;

 

     int myuinit (terminal_type)

     char terminal_type[];

 

DESCRIPTION

 

This function is a hook for application code at screen manager initialization

time. It is called immediately on entry to sm_initcrt, which treats it as if its

job were to determine the terminal type; however, it need not do that, and it

may do anything else. It receives, in terminal_type, the address of a buffer

where JAM stores its terminal type string; if it writes a null-terminated string

there, sm_initcrt will use that instead of checking the environment.

 

On operating systems without an environment, this function can be used to obtain

the terminal type in some system-specific way. It can be used to do

initializations, but those are better done before the call to sm_initcrt.

 

This function must be installed via a call to sm_install, q.v., using

UINIT_FUNC.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_initcrt (path);

     sm_install (which_hook, what_func, howmany);


 

NAME

 

 

     sm_u_ureset - screen manager cleanup hook

 

SYNOPSIS

 

     #include "smdefs.h"

 

     extern struct fnc_data *sm_u_ureset;

 

     void myureset ();

 

DESCRIPTION

 

sm_resetcrt calls this function just before returning; it provides a hook for

application-specific cleanup code. It receives no parameters, and any return

value is ignored. You should use sm_install to install it.

 

sm_resetcrt is normally called when the program catches an interrupt signal, or

exits normally; this is therefore a good place to attach processing that needs

to be done in the case of (abnormal) exit.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_resetcrt ();

     sm_install (which_hook, what_func, howmany);

     sm_cancel ();


 

NAME

 

 

     sm_u_vproc - video processing hook

 

SYNOPSIS

 

     #Include "smdefs.h"

 

     extern struct fnc_data *sm_u_vproc;

 

     int myvproc (operation, parameters)

     int operation;

     int *parameters;

 

DESCRIPTION

 

This function is a hook for video output. JAM defines generic video operations,

and uses a configuration file to support them on a given display. It calls this

function to display output, passing it a video operation code, and a vector of

parameters containing zero or more integers. The operation codes are defined in

smvideo.h , and are listed below.

 

       Code                 Operation     # Parameters

 

     V_INIT    initialization string

     V_RESET   reset string

     V_ED      erase entire display & home cursor

     V_EL      erase from cursor to end of line

     V_EW      erase window to given background

               5

     V_REPT    repeat character sequence     2

     V_CON     turn cursor on

     V_COF     turn cursor off

     V_INSON   set insert cursor style

     V_INSOFF  set overstrike cursor style

     V_SCP     save cursor position

     V_RCP     restore cursor position

     V_CUP     absolute cursor position      2

     V_CUU     cursor up                     1

     V_CUD     cursor down                   1

     V_CUF     cursor forward                1

     V_CUB     cursor back                   1

     V_SGR     set latch graphics rendition  11

     V_ASGR    set area graphics rendition   11

     V_ARGR    remove area attribute

     V_OMSG    open message line

     V_CMSG    close message line

     V_KSET    write to softkey label        2

     V_MODE0   set graphics mode 0

               (likewise V_MODE1, 2, 3)

     V_MODE4   single-character graphics mode

               (likewise V_MODE5, 6)

     BELL      visible alarm sequence

 

 

This hook enables you to add special processing for standard video operations,

should you wish to replace or extend them. If you have severe memory

constraints, you can use sm_u_vproc to hard-code all video processing and

eliminate the device-independent video package entirely, thus saving substantial

space. Not all codes defined there will be passed to this routine, just those

that actually produce output, as are shown in the table.


 

Your video function must be installed with a call to sm_install, using

VPROC_FUNC. If it returns a nonzero value, JAM's run-time system will process

the operation normally, so you need implement only those operations you are

really interested in.

 

Note: you may call the function you supply for this hook anything you like; it

is included in the manual under this head only for definiteness. In fact, the

name on this page is one you should not call your function, because it will

conflict with the global variable used by JAM to store your function's address.

 

RETURNS

 

     Zero if the parameters were successfully processed, nonzero otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_install (which_hook, what_func, howmany);


 

NAME

 

 

     sm_ch_umsgatts - change the standard error windows attributes

 

SYNOPSIS

 

     void sm_ch_umsgatt (border_style, border_attribute,

          protected_attribute, menu_attribute)

          int border_style;

          int border_attribute;

          int protected_attribute;

          int menu_attr;

 

DESCRIPTION

 

Changes the display characteristics of the error windows that are part of the

library. Currently, there are two such windows: the error window, used to

display a message too long to fit on the status line; and the hit space window,

which pops up if you hit any key other than the space bar to acknowledge an

error message.

 

This function is intended to be called once, at the beginning of an application,

to set the display characteristics of the library windows to harmonize with the

application's own forms.

 

This function is similar to sm_ch_form_atts, which changes the attributes of the

system calls and "go to" windows as well as those of the error windows. Use of

that function is therefore preferable.

 

If border_style is less than 0, the windows are made borderless. Otherwise, it

is taken to be the border style number (0 through 9), and border_attribute, if

nonzero, is made the border attribute.

 

If protect_attribute is nonzero, it is used for protected fields that contain

messages in the error windows. menu_attribute is not currently used.


 

NAME

 

     sm_ungetkey - push back a translated key on the input

 

SYNOPSIS

 

     #include "smkeys.h"

 

     int sm_ungetkey (key);

     int key;

 

DESCRIPTION

 

Saves the translated key given by key so that it will be retrieved by the next

call to sm_getkey.  Multiple calls are permitted; the key values are pushed onto

a stack (LIFO).

 

When sm_getkey reads a key from the keyboard, it flushes the display first, so

that the operator sees a fully updated display before typing anything. Such is

not the case for keys pushed back by sm_ungetkey; since the input is coming from

the program, it is responsible for updating the display itself.

 

RETURNS

 

     The value of its argument, or -1 if memory for the stack is unavailable.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_getkey ();

 

EXAMPLE

 

#include "smkeys.h"

 

/* Force tab to next field */

sm_ungetkey (TAB);


 

NAME

 

     sm_unprotect - completely unprotect a field

 

SYNOPSIS

 

     int sm_unprotect (field_number)

     int field_number;

 

DESCRIPTION

 

Removes all four kinds of protection (see table) from the field indicated by

field_number.

 

        Mnemonic       Meaning

 

        EPROTECT       protect from data entry

        TPROTECT       protect from tabbing into (or from

                       entering via any other key)

        CPROTECT       protect from clearing

        VPROTECT       protect from validation routines

 

 

To unprotect a field selectively, use sm_1unprotect; to unprotect an array as a

unit, use sm_aunprotect.

 

RETURNS

 

     -1 if the field is not found; 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_e_unprotect (field_name, element);

     sm_n_unprotect (field_name);

     sm_protect (field_number);

     sm_1unprotect (field_number, mask);

     sm_aunprotect (field_number, mask);

 

EXAMPLE

 

#include "smdefs.h"

 

/* If the executive has a PC, unprotect a field to

 * hold its make; otherwise, protect that field. */

 

if (sm_n_is_yes ("owns_pc"))

     sm_n_unprotect ("pc_make");

else sm_n_protect ("pc_make");


 

NAME

 

 

     sm_unsetup - restore screen manager options to their default values

 

SYNOPSIS

 

     void sm_unsetup ();

 

DESCRIPTION

 

This function calls all the option-setting library functions mentioned in the

setup file with their default parameters, effectively restoring "factory

defaults" to the whole library. There is a list of the functions involved in the

section on setup files in the Configuration Guide.

 

The values read in by sm_smsetup are not erased from memory.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_smsetup (memfile);

 

EXAMPLE

 

/* Back to defaults we go. */

 

sm_unsetup ();


 

NAME

 

 

     sm_vinit - initialize video translation tables

 

SYNOPSIS

 

     int sm_vinit (video_file)

     char *video_file;

 

DESCRIPTION

 

This routine is called by sm_initcrt as part of the initialization process. It

can also be called directly by an application program, with video_file the

address of a memory resident video file. Such a file must be created by the

JYACC vid2bin and bin2c utilities, then compiled into the application.

 

If video_file is zero, this function will read the binary file named by the

environment variable SMVIDEO from disk.

 

RETURNS

 

     0 if initialization is successful; -1 if video_file is zero and SMVIDEO is

          undefined; program exit if an error occurs in reading from disk.

 

EXAMPLE

 

/* Install a memory-resident video file */

 

extern char special_vid[];

 

sm_vinit (special_vid);


 

NAME

 

     sm_wdeselect - restore the formerly active window

 

SYNOPSIS

 

     int sm_wdeselect ();

 

DESCRIPTION

 

This function restores a window to its original position in the form stack,

after it has been moved to the top by a call to sm_wselect. Information

necessary to perform this feat is saved during each call to sm_wselect, but is

not stacked; therefore a call to this routine must follow a call to sm_wselect,

and select/deselect pairs cannot be nested.

 

RETURNS

 

     -1 if there is no window to restore. 0 otherwise.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wselect (window);

     sm_n_wselect (window_name);

 

EXAMPLE

 

/* A typical use of the window selection routines is to

 * update information to a window that may (or may not) be

 * covered.  For example, suppose that the current time

 * should be maintained on the underlying form.  Assume

 * that a field named "curtime" exists on that form.

 * The following code fragments can be used

 * to maintain that field independent of the number of windows

 * currently open above the form.

 */

 

#include "smdefs.h"

 

updatetime()

{

     sm_wselect (0); /* quietly select the bottom form */

     sm_n_putfield ("curtime", ""); /* update system time display */

     sm_wdeselect ();/* restore visible window */

     sm_flush ();

     return (0);

}

 

/* In initialization code: called every second. */

 

     static struct fnc_data afunc = { 0, updatetime, 0, 10, 0, 0 };

     sm_install (ASYNC_FUNC, &afunc, (int *)0);


 

NAME

 

     fnc(wrecord) - copy data from the screen or LDB to a structure

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_wrecord (structure_ptr, record_name, byte_count, lang);

     char *structure_ptr;

     char * record_name;

     int *byte_count;

     int lang;

 

DESCRIPTION

 

When a data dictionary containing records is run through the dd2struct utility,

structure definitions based on the fields of each record in the data dictionary

are saved in a file with the dictionary name plus a language-specific extension.

Including this file (or specific structures of the file) in an application

allows declarations of objects of these structure types. Such objects must be

declared for sm_rrecord and sm_wrecord to be used.

 

The argument structure_ptr is the address of one such declared structure. The

argument record_name is the name of the data dictionary record, needed for

looking up its attributes.

 

The argument byte_count is a pointer to an integer. Upon return from sm_wrecord,

the value contained in the integer will be the number of bytes or characters

read from or written to the structure. It will be 0 if an error occured.

 

The argument lang is the language number, as defined in smsmdefs.h . Zero stands

for C with null-terminated strings, one for C with blank-filled strings.

 

sm_wrecord reads field data from the screen if possible, or from the local data

block, and fills in the appropriate elements of the structure. If a structure

element is of a numeric type, the data is first converted into the appropriate

representation for the machine.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_rrecord (structure_ptr, record_name, byte_count, lang);


 

NAME

 

     sm_wrt_part - write part of the screen to a structure

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_wrt_part (form_struct, first_field,

          last_field, language)

     char *form_struct;

     int first_field, last_field, language;

 

DESCRIPTION

 

This function copies the contents of all fields between first_field and

last_field to a data structure in memory. An array and its scrolling items will

be copied only if the first element falls between first_field and last_field.

 

The address of the structure is in screen_struct; it is a structure for the

whole screen, not just the part of interest. There is a utility, JYACC f2struct,

that will automatically generate such a structure from the screen file.

 

Language stands for the programming language in which the structure is defined;

it controls the conversion of string and numeric data. Zero stands for C with

null-terminated strings, one for C with blank-filled strings.

 

If your screen is so designed that (for instance) the input and output fields

are grouped together, this function can be much faster than sm_wrtstruct, which

copies every field.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_rd_part (screen_structure, first_field, last_field, language);

     sm_wrtstruct (screen_structure, byte_count, language);

 

EXAMPLE

 

The code example below uses the same screen as the sm_rdstruct example; refer to

that example for the screen's picture and listing.

 

Here is a header file produced by f2struct from the screen:

 

struct strex

{

     long      date;

     char      name[26];

     char      address[3][76];

     char      telephone[14];

};

 

Finally, here is a program that processes the screen using sm_rd_part and

sm_wrtpart.

 

#include "smdefs.h"

#include "smkeys.h"

#include "strex.h"

 

#define C_LANG    0

 

int main ();

void punt ();

 

char *program_name;

main (argc, argv)

char *argv[];

{

     struct strex

     example;

     int       key;

     char      ebuf[80];

 

     /* Initialize all structure members to nulls. This is

      * important because we are going to do an sm_rd_part

      * first. */

     example.date = 0L;

     example.name[0] = 0;

     example.address[0][0] = example.address[1][0] = 0;

     example.address[2][0] = 0;

     example.telephone[0] = 0;

 

     /* Copy command line arguments, if any, into the structure. */

     switch (argc)

     {

     case 6:

     default:

     /* Ignore extras */

          strcpy (example.telephone, argv[5]);

     case 5:

          strcpy (example.address[2], argv[4]);

     case 4:

          strcpy (example.address[1], argv[3]);

     case 3:

          strcpy (example.address[0], argv[2]);

     case 2:

          strcpy (example.name, argv[1]);

          program_name = argv[0];

          break;

     }

 

     /* Initialize the screen and copy the structure to it,

      * excluding the date field. */

     sm_initcrt ("");

     if (sm_r_form ("strex") < 0)

          punt ("Cannot read form.");

     sm_rd_part (&example, 2, sm_numflds, C_LANG);

     sm_n_putfield ("date", "");

 

     /* Open the keyboard to accept new data to the form, and

      * copy it to the structure when done. Break out when user

      * hits EXIT key. */

     sm_d_msg_line ("Enter data; press %KEXIT to quit.",

          WHITE | HILIGHT);

     do {

          key = sm_openkeybd ();

          sm_wrtstruct (&example, 2, sm_numflds, C_LANG);

          sprintf (ebuf, "Acknowledged: byte count = %d.",

               count);

          sm_err_reset (ebuf);

     } while (key != EXIT);

 

     /* Clear the screen and display the final structure contents. */

     sm_resetcrt ();

     printf ("%s\n", example.name);

     for (count = 0; count < 3; ++count)

          if (example.address[count][0])

               printf ("%s\n", example.address[count]);

     printf ("%s\n", example.telephone);

     exit (0);

}

 

void

punt (message)

char *message;

{

     sm_resetcrt ();

     fprintf (stderr, "%s: %s\n", program_name, message);

     exit (1);

}


 

NAME

 

     sm_wrtstruct - copy data from the screen to a memory structure

 

SYNOPSIS

 

     #include "smdefs.h"

 

     void sm_wrtstruct (form_struct, count, language)

     char *form_struct;

     int *count, language;

 

DESCRIPTION

 

This function copies a data structure in memory to the screen, converting

individual items as appropriate. The address of the structure is in

screen_struct. There is a utility, JYACC f2struct, that will automatically

generate such a structure from the screen file.

 

The argument count is the address of an integer variable. sm_wrtstruct will

store there the number of bytes copied to the structure.

 

The argument language stands for the programming language in which the structure

is defined; it controls the conversion of string and numeric data. Zero stands

for C with null-terminated strings, one for C with blank-filled strings.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wrt_part (screen_structure, first_field, last_field, language);

     sm_rdstruct (screen_structure, byte_count, language);

 

EXAMPLE

 

The code example below uses this screen, whose picture and listing follow.

 

                  ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»

                  º                                         º

                  º  Name:      _________________________   º

                  º  Address:   _________________________   º

                  º             _________________________   º

                  º             _________________________   º

                  º  Telephone: (___)___-____               º

                  º                                         º

                  ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ

 

 

                            FORM 'strex'

                            ------------

 

FIELD DATA:

-----------

 

Field number        : 1   (line 1, column 32, length = 8)

Field name          : date

Display attribute   : UNDERLINED HIGHLIGHTED WHITE

Field edits         : PROTECTED FROM:  ENTRY OF DATA;  TABBING INTO;  CLEARING;

                       VALIDATION;

Date field data     : SYSTEM DATE; FORMAT = MM.DD.YY

Data type           : LONG INT

 

 

Field number        : 2   (line 3, column 15, length = 25)

Field name          : name

Display attribute   : UNDERLINED HIGHLIGHTED WHITE

Field number        : 3   (line 4, column 15, length = 25)

Field name          : address

Vertical array      : 3 elements; distance between

                      elements = 1

Array field numbers :  3  4  5

Shifting values     : maximum length = 75; increment =  1

Display attribute   : UNDERLINED HIGHLIGHTED WHITE

 

 

Field number        : 6   (line 7, column 15, length = 13)

Field name          : telephone

Display attribute   : UNDERLINED HIGHLIGHTED WHITE

Character edits     : DIGITS-ONLY

Data type           : CHAR STRING


 

Here is a header file produced by f2struct from the screen above.

 

struct strex

{

     long      date;

     char      name[26];

     char      address[3][76];

     char      telephone[14];

};

 

Finally, here is a program that processes the screen using sm_rdstruct and

sm_wrtstruct.

 

#include "smdefs.h"

#include "smkeys.h"

#include "strex.h"

 

#define C_LANG   0

 

int main ();

void punt ();

 

char *program_name;

 

main (argc, argv)

char *argv[];

{

     struct strex example;

     int       count,

               key;

     char      ebuf[80];

 

     /* Initialize all structure members to nulls. This is

      * important because we are going to do an sm_rdstruct

      * first. */

     example.date = 0L;

     example.name[0] = 0;

     example.address[0][0] = example.address[1][0] = 0;

     example.address[2][0] = 0;

     example.telephone[0] = 0;

 

     /* Copy command line arguments, if any, into the structure. */

     switch (argc)

     {

     case 6:

     default:

     /* Ignore extras */

          strcpy (example.telephone, argv[5]);

     case 5:

          strcpy (example.address[2], argv[4]);

     case 4:

          strcpy (example.address[1], argv[3]);

     case 3:

          strcpy (example.address[0], argv[2]);

     case 2:

          strcpy (example.name, argv[1]);

          program_name = argv[0];

          break;

     }

 

     /* Initialize the screen and copy the structure to it. */

     sm_initcrt ("");

     if (sm_r_form ("strex") < 0)

          punt ("Cannot read form.");

     sm_rdstruct (&example, &count, C_LANG);

     sm_n_putfield ("date", "");

 

     /* Open the keyboard to accept new data to the form, and

      * copy it to the structure when done. Break out when user

      * hits EXIT key. */

     sm_d_msg_line ("Enter data; press %KEXIT to quit.",

          WHITE | HILIGHT);

     do {

          key = sm_openkeybd ();

          sm_wrtstruct (&example, &count, C_LANG);

          sprintf (ebuf, "Acknowledged: byte count = %d.",

               count);

          sm_err_reset (ebuf);

     } while (key != EXIT);

 

     /* Clear the screen and display the final structure contents. */

     sm_resetcrt ();

     printf ("%ld\n", example.date);

     printf ("%s\n", example.name);

     for (count = 0; count < 3; ++count)

          if (example.address[count][0])

               printf ("%s\n", example.address[count]);

     printf ("%s\n", example.telephone);

 

     exit (0);

}

 

void

punt (message)

char *message;

{

     sm_resetcrt ();

     fprintf (stderr, "%s: %s\n", program_name, message);

     exit (1);

}


 

NAME

 

     sm_wselect - shuffle windows

 

SYNOPSIS

 

     int sm_wselect (window)

     int window;

 

DESCRIPTION

 

This routine brings a hidden window (or form) to the active position, where it

will be referenced by screen manager library calls such as sm_putfield and

sm_getfield. You identify the window you want by its sequence number in the

stack of windows: the form underlying all the windows is window 0; window = 1

gets the first window opened, window = 2 the second, and so forth.

 

Here are two different ways of using window selection. One is to select a hidden

screen momentarily, to update something in it, and replace it by calling

sm_wdeselect without opening the keyboard. This sequence will have no immediate

visible effect, unless sm_flush is called. The other is to select a hidden

screen and open the keyboard; in this case, the selected screen becomes visible,

and may hide part or all of the screen that was previously active. In this way

you can implement multipage forms, or switch among several windows that tile the

screen (do not overlap).

 

After this routine is called the order of the windows on the stack, and thus the

numbering of the windows, is changed. Subsequent calls to this function must be

aware of the current ordering of windows. The JAM screen stack is unaffected by

this function.

 

A related function sm_n_wselect, takes the name of a window as argument and

looks for it in the window stack. It will not find windows displayed with

sm_d_window or related functions, because they do not record the window name.

 

JAM applications should only use this routine in paired calls with sm_wdeselect,

or the control stack will become incorrect and unexpected results may occur.

 

RETURNS

 

     The number of the window that was made active (either the number passed, or

          the maximum if that was out of range). -1 if the system ran out of

          memory.

 

VARIANTS AND RELATED FUNCTIONS

 

     sm_wdeselect ();

     sm_n_wselect (window_name);


 

EXAMPLE

 

/* A typical use of the window selection routines is to

 * update information to a window that may (or may not) be

 * covered.  For example, suppose that the current time

 * should be maintained on the underlying form.  Assume

 * that a field named "curtime" exists on that form.

 * The following code fragments can be used

 * to maintain that field independent of the number of windows

 * currently open above the form.

 */

 

#include "smdefs.h"

 

updatetime()

{

     sm_wselect (0); /* quietly select the bottom form */

     sm_n_putfield ("curtime", ""); /* update system time display */

     sm_wdeselect ();/* restore visible window */

     sm_flush ();

     return (0);

}

 

/* In initialization code: called every second. */

 

     static struct fnc_data afunc = { 0, updatetime, 0, 10, 0, 0 };

     sm_install (ASYNC_FUNC, &afunc, (int *)0);


 

NAME

 

     sm_zm_options - set zooming options

 

SYNOPSIS

 

     #include "smdefs.h"

 

     int sm_zm_options (flag)

     int flag;

 

DESCRIPTION

 

Controls the behavior of the zooming function, normally bound to the ZOOM key.

Flag is a mnemonic defined in smdefs.h , or a pair of mnemonics ored together,

that select the operations desired.

 

Zooming makes more of scrolling and shifting fields visible than is ordinarily

the case. It expands the current field either horizontally or vertically, as far

as the physical display will allow, and places it in a window atop the currently

displayed screen. If a field is both scrolling and shifting, zooming will

ordinarily take place in two steps: scrolling expansion will be done first, and

shifting expansion next. If a scrolling field has parallel scrolls, they will be

displayed too.

 

The following mnemonics control scroll expansion:

 

   ZM_NOSCROLL         Scrolling arrays will not be expanded; the process

                       goes immediately to shift expansion.

   ZM_SCROLL           Scrolling arrays will be expanded to display as many

                       items as possible.

   ZM_PARALLEL         Scrolling arrays will be expanded to display as many

                       items as possible, along with their parallel arrays.

   ZM_1STEP            Scrolling arrays will be expanded to display as many

                       items as possible; shifting arrays will be expanded at

                       the same time. This option overides the shift mode

                       flag.

 

The following mnemonics control array/scrolling expansion when shifting fields

are being expanded in step two:

 

   ZM_NOSHIFT          Shifting fields will not be expanded; they will remain

                       shifting, and no second step takes place.

   ZM_SCREEN           Shifting arrays will have as many on-screen elements

                       as the previous form had. This will be the original

                       form ONLY if ZM_NOSCROLL is used; otherwise, ZM_SCREEN

                       means the scroll-expansion screen, or show as many

                       items as possible.

   ZM_ELEMENT          Show 1 element on-screen, but allow scrolling (via

                       arrow keys) to the rest of the array. If a scroll mode

                       was selected, the shift window can be zoomed again,

                       showing all elements.

   ZM_ITEM             Show only 1 element.  There is no way of seeing more

                       items in the "ITEM" scroll window.

 

Here are some useful combinations whose semantics are perhaps not crystal clear

from the above descriptions:

 

ZM_PARALLEL|ZM_SCREEN           This is the default, and zooms in two steps. The

                                first step will expand the scrolling arrays; the

                                second step will add expansion of shifting

                                fields, but lose the parallel arrays.

ZM_PARALLEL|ZM_ELEMENT          This will zoom in three steps, adding a

                                single-line shift expansion as step two.  This

                                will save screen update time when looking at a

                                single record.

ZM_NOSCROLL|ZM_SCREEN           This will disable scroll expansion, but the

                                shift expansion window will still show the items

                                that were on-screen in the original screen.

ZM_NOSCROLL|ZM_ELEMENT          This will minimize screen output when all that

                                is wanted is shift-expansion of an oversize

                                description field.

ZM_NOSCROLL|ZM_ITEM             This will restrict zoom to shift expansion of

                                only the current item.

ZM_1STEP                        This will always give the maximum data in the

                                first step. However, no parallel arrays are

                                displayed.

 

If you define the SMZMOPTIONS variable in your setup file, it will cause this

function to be called automatically during start-up with the parameters you

specify there.

 

RETURNS

 

     -1 if the parameter is invalid, otherwise the previous options.

 

EXAMPLE

 

#include "smdefs.h"

 

/* Restore zooming options to their defaults. */

 

sm_zm_options (ZM_PARALLEL | ZM_SCREEN);


 

4 Built-in Invoked Functions

 

This section describes invoked (caret) functions supplied with JAM. The format

of each page is similar to that of the preceding section, with a few exceptions.

The synopsis is for a JAM control string, not a programming language source

statement; boldface indicates keywords to be entered as shown, while normal type

indicates parameters to be replaced by a string you choose. The return value of

a caret function can only be used in a target list; see Section 1.2.1.

 

You may use these functions only in caret control strings. If you call them

directly from your own code a wide variety of results, ranging from perfect

success through obscure run-time problems to linker errors, is possible.


 

NAME

 

     jm_exit - end processing and leave the current screen

 

SYNOPSIS

 

     ^jm_exit

 

DESCRIPTION

 

Erases the current form or window and returns to the previous one. If the

current form is the last one on the control path (the application's top-level

form), will cause JAM to prompt and exit to the operating system.

 

The effect is like the default action of the run-time system's EXIT key.

 

EXAMPLE

 

The following control string invokes a function named process. If it returns 0,

another function is invoked to reinitialize the screen; but if it returns -1,

the screen is exited. See jm_gotop for another example.

 

     ^(-1=^jm_exit; 0=^reinit)process

 

The example below shows how a form or a window can be swapped with another form

or a window:

 

     ^(0=&w2)jm_exit


 

NAME

 

     jm_gotop - return to application's top-level form

 

SYNOPSIS

 

     ^jm_gotop

 

DESCRIPTION

 

Returns to the application's top-level screen, ordinarily the first screen to

appear when the application was run. All forms and windows on the control path

are discarded.

 

The run-time system's SPF1 key performs the same action, unless you change it

using SMINICTRL.

 

EXAMPLE

 

The following menu makes use of both jm_exit and jm_gotop.

 

              ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»

              º                                                 º

              º  Query customer database__    custquery.jam__   º

              º  Update customer database_    custupdate.jam_   º

              º  Free-form query__________    !sql___________   º

              º  Return to previous menu__    ^jm_exit_______   º

              º  Return to main menu______    ^jm_gotop______   º

              º                                                 º

              ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ


 

NAME

 

     jm_goform - prompt for and display an arbitrary form

 

SYNOPSIS

 

     ^jm_goform

 

DESCRIPTION

 

This function pops up a window in which you may enter the name of a form; it

will then close the window and attempt to display the form, as if that form's

name had appeared in a control string. It is useful for providing a shortcut

around a menu system for experienced users.

 

The result is the same as the default action of the run-time system's SPF3 key.

 

EXAMPLE

 

The following line, if placed in your setup file, will make the PF10 key act

like SPF3 normally does:

 

     SMINICTRL= PF10=^jm_goform


 

NAME

 

     jm_keys - simulate keyboard input

 

SYNOPSIS

 

     ^jm_keys keyname-or-string [keyname-or-string ...]

 

DESCRIPTION

 

Queues characters and function keys that appear after the function name for

input to the run-time system, using sm_ungetkey. The run-time system then

behaves as though you had typed the keys.

 

Function keys should be written using the logical key mnemonics listed in

smkeys.h . Data characters should be enclosed between apostrophes '', backquotes

``, or double quotes "". This function passes its arguments to sm_ungetkey in

reverse order, so you supply them in the natural order.

 

EXAMPLE

 

Enter the name of your favorite bar, followed by a tab and the name of its

owner:

 

     ^jm_keys 'Steinway Brauhall' TAB "James O'Shaughnessy"

 

Return to the preceding menu and choose the second option:

 

     ^jm_keys EXIT HOME TAB XMIT


 

NAME

 

     jm_mnutogl - switch between menu and data entry mode on a dual-purpose

                  screen

 

SYNOPSIS

 

     ^jm_mnutogl

 

DESCRIPTION

 

JAM supports the use of a single screen for both menu selection and data entry;

one popular example is a data entry screen with a "menu bar". The screen must,

however, be either one or the other at any given moment. This function switches

the run-time system's treatment of the screen to the other mode. When the screen

is a menu, the run-time system uses sm_menu_proc for keyboard input; otherwise,

it uses sm_openkeybd.

 

Screens with a jam_menu field will be treated initially as menus; others will be

treated initially as data entry screens. A screen cannot be used as a menu

unless it has fields with the MENU bit set.

 

EXAMPLE

 

Below is a screen with four menu options on the left and data entry fields on

the right. Selecting a menu option first causes a function to be invoked, which

will store the choice; when that function returns zero, jm_mnutogl is invoked to

begin data entry. When data entry is completed by the TRANSMIT key, a function

attached to that key can use the stored menu option to perform the desired

transaction.

 

       ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»

       º                       º  Name:    __________________________  º

       º     LOOKUP            º  Address: __________________________  º

       º ^(0=^jm_mnutogl)look  º           __________________________  º

       º     ADD___            º           __________________________  º

       º ^(0=^jm_mnutogl)add_  º  Phone:   (___)___-____               º

       º     MODIFY            º  Notes:   __________________________  º

       º ^(0=^jm_mnutogl)mod_  º           __________________________  º

       º     DELETE            º           __________________________  º

       º ^(0=^jm_mnutogl)del_  º           __________________________  º

       ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ


 

NAME

 

     jm_system - prompt for and execute an operating system command

 

SYNOPSIS

 

     ^jm_system

 

DESCRIPTION

 

This function pops up a small window, in which you may enter an operating system

command. When you press TRANSMIT, it closes the window and executes the command.

While the command is executing, your terminal is returned to the operating

system's default I/O mode.

 

The run-time system's SPF2 key invokes this function by default.

 

EXAMPLE

 

The following line, when placed in your setup file, will cause the PF10 key to

act as SPF2 normally does:

 

     SMINICTRL= PF10 = ^jm_system


 

NAME

 

     jpl - invoke a JPL procedure stored in a file

 

SYNOPSIS

 

     ^jpl filename [ argument ... ]

 

DESCRIPTION

 

This function invokes a procedure written in the JYACC Procedural Language and

stored in a file. Filename should be the name of the file containing your

procedure; anything following that will be passed to the procedure as arguments.

The value returned by your procedure will be passed along by jpl for use in a

target list.

 

This function is similar to the JPL jpl command, but does not do colon

expansion.

 

EXAMPLE

 

The control string below invokes a JPL function, passing it the name of a field

in which its command is stored.

 

     ^jpl execute command


 

5 Environment and Configuration Files

 

This section describes only an essential few of the many configuration variables

supported by JAM; refer to the section on setup files in the Configuration Guide

for more. The following list summarizes JAM's most commonly used environment

variables:

 

   SMMSGS      file name for message text SMVIDEO

               file name for video information SMKEY

               file name for keyboard translation SMVARS

               single variable for consolidation TERM

               terminal mnemonic SMTERM

               substitute for TERM

 

The first three are required: they name configuration files used by JAM to

describe its operating environment. It finds them by looking either in the

system environment, or in a binary file named by SMVARS. If it fails to find

either the variables or the configuration files themselves, it will post a

message and exit.

 

The system variable TERM and the JAM variable SMTERM are used in conjunction

with SMVARS. You may replace the three environment variables with SMVARS. This

variable gives the name of a binary file containing the other screen manager

variables. A typical SMVARS source file might look like the following:

 

     SMKEY = (TV:TV950)/sm/config/TVkeys.bin SMKEY =

     (vt100:d0:d1:d2)/sm/config/vt100keys.bin SMVIDEO = /sm/config/vt100vid.bin

     SMMSGS = /usr/local/msgfile.bin SMPATH = /appl/masks

 

The lists enclosed in parentheses are terminal types; JAM uses them to find the

right files for your terminal. The SMVARS source file must be converted to

binary using var2bin; the system environment then needs only the name of the

binary file (and perhaps your terminal), as

 

     SMVARS=/usr/local/smvars.bin

     TERM=vt100

 

The terminal type, used to match against the lists in parentheses, is taken from

the variable SMTERM, or from TERM if that is not present. (If you want JAM to

recognize a terminal mnemonic different from TERM, put it in SMTERM. For

example, the text editor might work fine with the terminal in vt100 emulation,

but JAM could want the features of vt220 emulation; you could set TERM to vt100

and SMTERM to vt220.)

 

Application programs initialize JAM by calling sm_initcrt. This call must

precede calls to just about any other library routine, except those that install

memory resident message, key and/or video files, or set options; see Section

12.2. sm_initcrt first calls an optional user-supplied initialization routine,

sm_u_uinit, which may (among other things) initialize the character string

sm_term.

 

sm_initcrt then looks for SMVARS and SMSETUP in the system environment, and uses

them to read in setup files. Subsequently, setup variables are sought first in

the system environment and then in the setup files.

 

Next the terminal type is determined and placed in a character array called

sm_term, which is declared in smdefs.h . An  application program can force a

terminal type by setting sm_term before sm_initcrt is called. If the array is

empty, SMTERM is sought first, then TERM. If neither is found, initialization is

attempted without a terminal type.

 

SMMSGS comes next. If this variable is not found, or the file it names is found

by sm_msginit not to be useable, JAM will abort initialization. Initialization

errors in file I/O are reported using the C library function perror; these

messages are system-dependent. Other errors encountered before the message file

is loaded provoke hard-coded messages; afterward, all error messages are taken

from the message file.

 

Video and keyboard initialization are next attempted, in that order, using

sm_keyinit and sm_vinit respectively. If after all this JAM still can't

determine which configuration files to use, it will prompt you for a terminal

type and retry the entire sequence. Finally, JAM initializes the terminal and

its operating system channel.

 

After ensuring that the environment is set up, sm_initcrt initializes the

operating system's terminal channel. It is set to "no echo" and non-buffered

input. If other changes are desired (e.g. from 7 to 8 data bits), they can be

made in the user initialization routine.

 

Next the initialization string found in the video file is transmitted to the

terminal. The Video Manual gives details; here we simply note that system calls

can be embedded in the string. Often this feature can be used in lieu of a user

initialization routine.

 

6 Keyboard Input

 

Keystrokes are processed in three steps. First, the sequence of characters

generated by one key is identified. Next the sequence is translated to an

internal value, or logical character. Finally, the internal value is either

acted upon or returned to the application ("key routing"). All three steps are

table-driven. Hooks are provided at several points for application processing;

they are described in Section 8.

 

6.1  Logical Characters or Keys

 

JAM processes characters internally as logical values, which frequently (but not

always) correspond to the physical ASCII codes used by terminal keyboards and

displays. Specific keys or sequences of keys are mapped to logical values by the

key translation table, and logical characters are mapped to video output by the

MODE and GRAPH commands in the video file. For most keys, such as the normal

displayable characters, no explicit mapping is necessary. Certain ranges of

logical characters are interpreted specially by JAM; they are

 

   .

      0x0100 to 0x01ff: operations such as tab, scrolling, cursor motion

   .

      0x6101 to 0x7801: function keys PF1 - PF24

   .

      0x4101 to 0x5801: shifted function keys SPF1 - SPF24

   .

      0x6102 to 0x7802: application keys APP1 - APP24

 

6.2  Key Translation

 

The first two steps together are controlled by the key translation table, which

is loaded during initialization. The name of the table is found in the

environment (see Section 5 for details). The table itself is derived from an

ASCII file which can be modified by any editor; a screen-oriented program,

modkey, is also supplied for creating and modifying key translation tables (see

the Configuration Guide).

 

After the table is read into memory, it has the form of an array  of structures:

 

     struct

     {

          char key[6];

          int value;

     };

The first field is an array of up to 6 characters; it holds the sequence of

characters sent to the computer when the key is pressed. The second member is

the logical value of the key.

 

JAM assumes that the first character of a multi-character key sequence is a

control character in the ASCII chart (0x00 to 0x1f, 0x7f, 0x80 to 0x9f, or

0xff). All characters not in this range are assumed to be displayable characters

and are not translated. The routine that performs the translation is called

sm_getkey.

 

Upon receipt of a control character, sm_getkey searches the translation table.

If no match is found on the first character, the key is accepted without

translation. If a match is found on the first character and the next character

in the table's sequence is 0, an exact match has been found, and sm_getkey

returns the value indicated in the table. The search continues through

subsequent characters until either

 

  1.  an exact match on n characters is found and the n+1'th character in the

      table is zero, or n is 6. In this case the value in the table is

      returned.

  2.  an exact match is found on n-1 characters but not on n. In this case

      sm_getkey attempts to flush the sequence of characters  returned by the

      key.

 

This last step is of some importance: if the operator presses a function key

that is not in the table, the screen manager must know "where the key ends."

The algorithm used is as follows. The table is searched for all entries that

match the first n-1 characters and are of the same type in the n'th character,

where the types are digit, control character, letter, and punctuation. The

smallest of the total lengths of these entries is assumed to be the length of

the sequence produced by the key. (If no entry matches by type at the n'th

character, the shortest sequence that matches on n-1 characters is used.)  This

method allows sm_getkey to distinguish, for example, between the sequences ESC O

x, ESC [ A, and ESC [ 1 0 ~.

 

6.3  Key Routing

 

The main routine for keyboard processing is sm_openkeybd. This routine calls

sm_getkey to obtain the translated value of the key. It then decides what to do

based on the following rules.

 

If the value is greater than 0x1ff, sm_openkeybd returns to the caller with this

value as the return code.

 

If the value is between 0x01 and 0x1ff, the processing is determined by a

routing table. This is an array whose address is stored in sm_route_table. The

value returned by sm_getkey is used to index into the table, where two bits

determine the action. The bits are examined independently, so four different

actions are possible:

 

   .

      If neither bit is set, the key is ignored.

   .

      If the EXECUTE bit is set and the value is in the range 0x01 to 0xff,

      it is written to the screen (as interpreted by the GRAPH entry in the

      video file, if one exists). If the value is in the range 0x100 to

      0x1ff, the appropriate action (tab, field erase, etc.) is taken.

   .

      If the RETURN bit is set, sm_openkeybd returns the logical value to the

      caller; otherwise, sm_getkey is called for another value.

   .

      If both bits are set, the key is executed and then returned.


 

The default settings are ignore for ASCII and extended ASCII control characters

(0x01 - 0x1f, 0x7f, 0x80 - 0x9f, 0xff), and EXECUTE only for all others. The

application function keys (PF1-24, SPF1-24, APP1-24, and ABORT) are not handled

through the routing table. Their routing is always RETURN, and cannot be

altered.

 

Applications can change key actions on the fly by modifying the routing table.

For example, to disable the backtab key the application program would execute

 

     sm_route_table[BACK] = 0;

 

To make the field erase key return to the application program, use

 

     sm_route_table[FERA] = RETURN;

 

Key mnemonics can be found in the file smkeys.h .

 

 

7 Screen Output

 

JAM uses a sophisticated delayed-write output scheme, to minimize unnecessary

and redundant output to the display. No output at all is done until the display

must be updated, either because keyboard input is being solicited or the library

function sm_flush has been called. Instead, the run-time system does screen

updates in memory, and keeps track of the display positions thus "dirtied".

Flushing begins when the keyboard is opened; but if you type a character while

flushing is incomplete, the run-time system will process it before sending any

more output to the display. This makes it possible to type ahead on slow lines.

You may force the display to be updated by calling sm_flush.

 

JAM takes pains to avoid code specific to particular displays or terminals. To

achieve this it defines a set of logical screen operations (such as "position

the cursor"), and stores the character sequences for performing these operations

on each type of display in a file specific to the display. Logical display

operations and the coding of sequences are described in excruciating detail in

the Video Manual; the following sections, along with Sections 11.2, and 12.4,

describe additional ways in which applications may use the information encoded

in the video file.

 

7.1  Graphics Characters and Alternate Character Sets

 

Many terminals support the display of graphics or special characters through

alternate character sets. Control sequences switch the terminal among the

various sets, and characters in the standard ASCII range are displayed

differently in different sets. JAM supports alternate character sets via the

MODEx and GRAPH commands in the video file.

 

The seven MODEx sequences (where x is 0 to 6) switch the terminal into a

particular character set. MODE0 must be the normal character set. The GRAPH

command maps logical characters to the mode and physical character necessary to

display them. It consists of a number of entries whose form is

 

     logical value = mode physical-character

 

When JAM needs to output logical value it will first transmit the sequence that

switches to mode, then transmit physical-character. It keeps track of the

current mode, to avoid redundant mode switches when a string of characters in

one mode (such as a graphics border) is being written. MODE4 through MODE6

switch the mode for a single character only.


 

7.2  The Status Line

 

JAM reserves one line on the display for error and other status messages. Many

terminals have a special status line (not addressable with normal cursor

positioning); if such is not the case, JAM will use the bottom line of the

display for messages. There are several sorts of messages that use the status

line; they appear below in priority order.

 

  1.  Transient messages issued by sm_err_reset or a related function

  2.  Ready/wait status

  3.  Messages installed with sm_d_msg_line or sm_msg

  4.  Field status text

  5.  Background status text

 

There are several routines that display a message on the status line, wait for

acknowledgement from the operator, and then reset the status line to its

previous state: sm_query_msg, sm_err_reset, sm_emsg, sm_quiet_err, and

sm_qui_msg. sm_query_msg waits for a yes/no response, which it returns to the

calling program; the others wait for you to acknowledge the message. These

messages have highest precedence.

 

sm_setstatus provides an alternating pair of background  messages, which have

next highest precedence. Whenever the keyboard is open for input the status line

displays Ready; it displays Wait when your program is processing and the

keyboard is not open. The strings may be altered by changing the SM_READY and

SM_WAIT entries in the message file.

 

If you call sm_d_msg_line, the display attribute and message text you pass

remain on the status line until erased by another call or overridden by a

message of higher precedence.

 

When the status line has no higher priority text, the screen manager checks the

current field for text to be displayed on the status line. If the cursor is not

in a field, or if it is in a field with no status text, JAM looks for background

status text, the lowest priority. Background status text can be set by calling

sm_setbkstat, passing it the message text and display attribute.

 

In addition to messages, the rightmost part of the status line can display the

cursor's current screen position, as, for example, C 2,18. This display is

controlled by calls to sm_c_vis.

 

During debugging, calls to sm_err_reset or sm_quiet_err can be used to provide

status information to the programmer without disturbing the main screen display.

Keep in mind that these calls will work properly only after screen handling has

been initialized by a call to sm_initcrt. sm_err_reset and sm_quiet_err can be

called with a message text that is defined locally, as in the following

examples:

 

1.   sm_err_reset ("Zip code invalid for this state.");

 

2.   int i, j;

     char bugbuf[81];

     sprintf (bugbuf, "i = %d; j = %d.", i, j);

     sm_quiet_err (bugbuf);

 

 

However, the JAM library functions use a set of messages defined in an internal

message table. This is accessed by the function sm_msg_get, using a set of

defines in the header file smerror.h . For example:

 

     sm_quiet_err (sm_msg_get (SM_MALLOC));


 

The message table is initialized from the message file identified  by the

environment variable SMMSGS. Application messages can also be placed in the

message file. See the section on message files in the Configuration Guide.

 

8 User-definable Functions

 

The JAM library contains numerous hooks where you can install routines to be

called from someplace within the run-time system. This is occasionally necessary

when you have exotic hardware, but more often it is simply convenient to do some

application-specific function in the context of a run-time system operation. The

keyboard input functions, for instance, contain several hooks.

 

A hook tells JAM everything it needs to know in order to call your routine. This

generally includes the routine's name, its address, and the programming language

it was written in. JAM knows how to interpret the routine's arguments and return

value by which hook it is installed on.

 

The following list itemizes all the different hooks and tells where to go for

information about each; the boldface references are to Section 3 of this

chapter. Many hooks hold a single application routine, but the first three in

the list can hold any number. In this case JAM uses the routine name, such as

the one you specify in the screen for an attached function, to find the

information it needs.

 

   .

      Screen entry and exit functions, Section 1.4

   .

      Attached functions, including field entry, field exit (or validation),

      and attached JPL procedure, Section 1.3

   .

      Invoked functions, Section 1.2

   .

      Memo edits, Section 8.2

   .

      Keystroke processing hooks:

 

         .

            Key translation function, sm_u_keychange

         .

            Key recording hook, sm_u_record

         .

            Key playback hook, sm_u_play

         .

            Key lookahead hook, sm_u_avail

         .

            Asynchronous function, sm_u_async

 

   .

      Display processing hooks:

 

         .

            Video processing hook, sm_u_vproc

         .

            Insert mode transition function, sm_u_inscrsr

         .

            Status line display function, sm_u_statfnc

 

   .

      Screen manager initialization and reset hooks, sm_u_uinit and

      sm_u_ureset

   .

      Check digit validation, sm_u_ckdigit


 

The hooks for which library function names are given are all documented under

those names in the library section of this chapter, and should be installed

using sm_install; the next section discusses installation. Attached, invoked

(caret), and screen entry functions are discussed in Sections 1.3, 1.2, and 1.4,

respectively. Memo edits are discussed below.

 

8.1  Installation

 

In general, there are two ways of getting JAM to call an application routine.

One is to write a routine in C with the same name and calling sequence as one

provided in the library, and link it with the application; the linker will then

ignore the library routine and load the application routine in its place. You

can use this technique for the sm_u_uinit, sm_u_ureset, video, and check digit

functions. This mechanism will not work on many systems. It is supported for

backward compatibility only, and may be phased out in the future.

 

The other technique is to call sm_install, q.v.; this is portable, supported,

and strongly to be preferred. You pass this function a data structure containing

the name, address, and source language of your function. Every function or type

of function listed in the previous section (with the exception of memo edits)

can be installed with sm_install.

 

8.2  Memo Text Edits

 

Memo text edits are not function hooks; rather, they are special edits you can

use to attach arbitrary information to a field. The JAM run-time system ignores

memo edits, but application routines may access them, using sm_edit_ptr. An

example of memo edit use follows.

 

Suppose a screen contains fields whose contents are interdependent, such as

state abbreviation and zip code. The zip code field might have an attached

function that performs a validation based on the state abbreviation. However, if

the zip code was validated and the operator subsequently changed the state

abbreviation, the zip code might become invalid. A simple solution would be to

attach the following function to the state abbreviation field:

 

int state_change (field_num, data, occurrence, val_mdt)

{

     if (val_mdt & MDT)

                       /* current field changed */

          sm_n_novalbit ("zip"); /* reset zip VALIDED bit*/

     return 0;

}

 

Now suppose a screen contains several groups of interdependent fields. One could

use MEMO1 to hold a list of dependent fields (say by number, separated by

commmas), and the following function to process them:


 

field_change (field_num, data, occurrence, val_mdt)

int field_num;

char *data;

int occurrence;

int val_mdt;

{

     char *ptr;

 

     if (val_mdt & MDT) /* current field changed */

     {

          ptr = sm_edit_ptr (field_number, MEMO1);

          if (ptr)      /* find MEMO1 edit, if any */

          {

               ptr += 2;

                  /* skip length, command code*/

               while (*ptr)

               {

                    sm_novalbit (atoi (ptr));

                    while (*ptr && *ptr != ',')

                         ++ptr;

                    if (*ptr) ++ptr;

               }

          }

     }

     return (0);

}

 

 

9 The Local Data Block

 

The LDB is a table of name-value pairs maintained by the run-time system. As you

enter data in named fields, the values are copied to the LDB; when you bring up

a new screen with named fields, values are copied in from the LDB. This

procedure implements data links, and goes by the name of LDB write-through. The

list of names is taken from the data dictionary; certain other field

characteristics needed for the proper formatting of data, such as field size and

currency formats, are also taken from the data dictionary.

 

During screen display, i.e. during execution of sm_r_window or a variant,

sm_allget is called to load named fields with values from the LDB (without

setting their MDT bits). Whenever a screen is removed from the display or is

covered by a window, sm_lstore is first called to update the LDB with screen

values. In between, i.e. while the screen is being processed, certain library

functions requiring data values seek them first in the screen, and search the

LDB if they are not there. This preserves the illusion that named fields in the

LDB are always accessible and always have the latest values in them. Screens

brought up by the run-time system share this feature with those brought up by

your control fields and code, since the run-time system uses sm_r_window too.

 

The library functions that use the LDB are n_ and i_ variants, plus a few that

reference the LDB explicitly, such as sm_lreset and sm_allget. Functions that

refer to a field by number, namely the o_ variant and the basic function,

obviously cannot access data outside the screen. The e_ functions do refer to

fields by name; however, they are designed specifically for accessing elements

of onscreen arrays, and so do not go to the LDB. Field calculation expressions

and JPL procedures that contain named fields will reference the LDB in the same

way.

 

If the scope of an LDB entry is 1, or constant, its value cannot be changed by

write-through; only sm_lreset can change the values of constants.

 

LDB write-through is normally on; you can turn it off (and back on) by calling

sm_dd_able. Care is necessary, though; even the explicit LDB access functions,

such as sm_allget, do not work when write-through is off. As an example, you

could make the LDB read-only in a single screen by putting the following code

fragment in a screen entry function:

 

     sm_allget (1);

     sm_dd_able (0);

 

You would then have to call sm_dd_able (1) to re-enable LDB write-through in a

screen exit function, which is called after the sm_lstore; calling it before

then, as in an EXIT control string, would cause the LDB to be updated. If you

want to disable LDB processing for an entire application, simply omit the call

to sm_ldb_init before starting up the run-time system; see Section 1.6.

 

10 Writing Portable Applications

 

The following section is an attempt to identify features of hardware and

operating system software that can cause JAM to behave in a non-uniform fashion.

An application designer wishing to create programs that run across a variety of

systems will need to be aware of these factors.

 

10.1  Terminal Dependencies

 

JAM can run on screens of any size. On screens without a separately addressable

status line, JAM will steal the bottom line of the display (often the 24th) for

a status line, and status messages will overlay whatever is on that line. A good

lowest common denominator for screen sizes is 23 lines by 80 columns, including

the border (if any).

 

Different terminals support different sets of attributes. JAM makes sensible

compromises based on the attributes available; but programs that rely

extensively on attribute manipulation to highlight data may be confusing to

users of terminals with an insufficient number  of attributes.

 

Attribute handling can also affect the spacing of fields and text. In

particular, anyone designing screens to run on terminals with onscreen

attributes must remember to leave space between fields, highlighted text, and

reverse video borders for the attributes. Some terminals with area attributes

also limit the number of attribute changes permitted per line (or per screen).

 

The key translation table mechanism supports the assignment of any key or key

sequence to a particular logical character. However, the number and labelling of

function keys on particular keyboards can constrain the application designer who

makes heavy use of function keys for program control. The standard VT100, for

instance, has only four function keys properly speaking. For simple choices

among alternatives, the library routines sm_menu_proc and sm_choice are probably

better than switching on function keys.

 

Using function key labels, or keytops, instead of hard-coded key names is also

important to making an application run smoothly on a variety of terminals. Field

status text and other status line messages can have keytops inserted

automatically, using the %K escape. No such translation is done for strings

written to fields; in such cases, you may want to place the strings in a message

file, since your setup file can now specify terminal-dependent message files.

 

10.2  Items in smmach.h

 

The header file smmach.h , which is supplied with the JAM  library, contains

information that library routines need to deal  with certain machine, operating

system, and compiler dependencies. These include:

 

   .

      The presence of certain C header files and library functions.

   .

      Byte ordering in integers and support for the unsigned character type.


 

   .

      Path name and command line argument separator characters.

   .

      Pointer alignment and structure padding.

 

The header file is thoroughly commented, and application designers are

encouraged to make use of the information there.

 

11 Writing International Applications

 

11.1  Messages

 

All messages displayed by the JAM library routines are in the ASCII message

file; this file may be edited to translate the messages into any language.

Further, the screens used by JAM utilities are supplied in libraries; they may

be edited there and their prompts translated.

 

11.2  Characters Outside the U.S. ASCII Set

 

Terminals that are capable of displaying characters outside the 7-bit U.S. ASCII

set may do it two ways: either they display 8-bit characters (those in the range

0x80 to 0xff), or they have control sequences for switching among several

character sets. On input, again, the foreign keys may generate either 8-bit

codes or a multi-character sequence.

 

If the terminal's keyboard generates 8-bit codes and its display  can display

them, there is little the application needs to do except  set the GRTYPE entry

in the video file. However, some caution is necessary, because JAM reserves the

range 0x100 to 0x1ff for its logical operations (tab, field erase, scroll,

etc.). Applications should avoid mapping keys into this range. Alternate

character sets require more work. First a logical value for the character in

question must be selected; the range 0xa0 to 0xfe is good. Next, the control

sequences for switching character sets must be defined in the video file as

MODEx. MODE0 is the normal character set; JAM supports up to 6 alternate

character sets (MODE1 to MODE6). Finally, the GRAPH entry in the video file must

be set up. It consists of any number of sub-entries whose format is

 

     logical-value = mode physical-character

 

where mode is 1 to 3 and logical-value is the value that gives the desired

output in the appropriate mode. (See Section 6.1 for more details on alternate

character sets, and the Video Manual for how to create and use video files.)

 

12 Writing Efficient Applications

 

12.1  Memory-resident Screens

 

Memory-resident screens are much quicker to display than disk-resident screens,

since no disk access is necessary to obtain the screen data. There are two ways

of using the JAM library functions with memory-resident screens; but in either

case, the screens must first be converted to source language modules with bin2c

or a related utility (see the Configuration Guide), then compiled and linked

with the application program.

 

sm_d_form and related library functions can be used to display memory-resident

screens; each takes as one of its parameters the address of the global array

containing the screen data, which will generally have the same name as the file

the original screen was originally stored in.

 

A more flexible way of achieving the same object is to use a memory-resident

screen list. Bear in mind that the JAM utility can only operate on disk files,

so that altering memory-resident screens during program development requires a

tedious cycle of test - edit - reinsert with bin2c - recompile. The JAM library

maintains an internal list of memory-resident screens that sm_r_window and

related functions examine. Any screen found in the list will be displayed from

memory, while screens not in the list will be sought on disk. This means that

the application can be coded to use one set of calls, the r-version, and screens

can be configured as disk- or memory-resident simply by altering the list.

 

The screen list is pointer to an array of structures:

 

struct form_list

{

     char *form_name;

     char *form_ptr;

} *sm_memforms;

 

 

To initialize it, an application would use code like the following:

 

#include "smdefs.h"

extern char mainform[], popup1[];

extern char popup2[], helpwin[];

 

struct form_list mrforms[] =

{

     "mainform.jam",mainform,

     "popup1.jam",  popup1,

     "popup2.jam",  popup2,

     "helpwin.jam", helpwin,

     "",            (char *)0

 

};

...

sm_formlist(mrforms);

 

Note the last entry in the screen list: an empty string for the name and a null

pointer for the screen data. This marks the end of the list, and is required.

The call to sm_formlist adds the screrens in your list to JAM's internal list.

 

Using memory-resident screens (and configuration files, see the next section)

is, of course, a space-time tradeoff: increased memory usage for better speed.

 

The naming of screens in the screen list presents a few problems. First of all,

the name of the character array for a screen must not conflict with the name of

any other global data item or function; for instance, a memory-resident screen

with the name of a function could not be installed with a program. Secondly, the

filename extension must be removed from the array name, which means that screens

with the same name but different extensions will conflict. If your application

code structure permits, you can minimize the foregoing problems by making the

screens in question local in scope to a particular source file.

 

JAM will append the extension found in the setup variable SMFEXTENSION to screen

names (e.g. in control fields) that do not already contain an extension; you

must take this into account when creating the screen list. JAM may also convert

the name to uppercase before searching the screen list; this is governed by the

SMFCASE variable.

 

12.2  Memory-resident Configuration Files

 

Any or all of the three configuration files required by JAM  can be made memory

resident. First a C source file must be created from the text version of the

file, using the bin2c utility; see the Configuration Guide. The source files

created are not intended to be modifiable, or even understandable, any more than

the binary files are; each defines some data objects which are of no concern to

us. Each file contains one data object that is globally known. The following

fragment makes all three files memory-resident:


 

     /* Memory-resident message, key, and video files */

     extern char msg_file[];

     extern char key_file[];

     extern char video_file[];

 

     /* ...more declarations... */

 

     sm_msginit (msg_file);

     sm_keyinit (key_file);

     sm_vinit (video_file);

     sm_initcrt ("");

 

     /* ...possibly initialize function and form lists  */

 

     /* ...application code */

 

 

If a file is made memory-resident, the corresponding environment variable or

SMVARS entry can be dispensed with.

 

12.3  Message File Options

 

If you need to conserve memory and have a large number of messages in message

files, you can make use of the MSG_DSK option to sm_msgread. This option avoids

loading the message files into memory; instead, they are left open, and the

messages are fetched from disk when needed. Bear in mind that this uses up

additional file descriptors, and that buffering the open file consumes a certain

amount of system memory; you will gain little unless your message files are

quite large.

 

12.4  Avoiding Unnecessary Screen Output

 

Several of the entries in the JAM video file are not logically necessary, but

are there solely to decrease the number of characters transmitted to paint a

given screen. This can have a great impact on the response time of applications,

especially on time-shared systems with low data rates; but it is noticeable even

at 9600 baud. To take an example: JAM can do all its cursor positioning using

the CUP (absolute cursor position) command. However, it will use the relative

cursor position commands (CUU, CUD, CUF, CUB) if they are defined; they always

require fewer characters to do the same job. Similarly, if the terminal is

capable of saving and restoring the cursor position itself (SCP, RCP), JAM  will

use those sequences instead of the more verbose CUP.

 

The global flag sm_do_not_display may also be used to decrease screen output.

While this flag is set, calls into the JAM library will cause the internal

screen image to be updated, but nothing will be written to the actual display;

the latter can be brought up to date by resetting the flag and calling

sm_rescreen. With the implementation of delayed write in JAM Release 4, this

sort of trick is necessary much less often than it was under Release 3.

 

12.5  Stub Functions

 

Certain screen manager facilities can be omitted from an application if they are

not used, by defining certain literals in the application. This can result in

substantial memory savings; however, it requires that the screen manager

libraries not be pre-linked or pre-bound, i.e. is not supported on all systems.

The following facilities may be stubbed out:


 

              subsystem            #define

 

          the math package         NOCALC scrolling functions

                                   NOSCROLL time and date functions

                                   NOTIMEDATE help screens

                                   NOHELP shifting fields

                                   NOSHIFT range checking functions

                                   NORANGE word wrap

                                   NOWRAP field zoom expansion

                                   NOZOOM regular expressions

                                   NOREGEXP form libraries

                                   NOFORMLIB JYACC procedural language

                                   NOJPL read/write data structure

                                   NOSTRUCT save/restore screen data

                                   NOSRD local print

                                   NOLPR area attributes

                                   NOAREA window selection

                                   NOWSEL keytop translation

                                   NOLKEYLAB setup parameter file

                                   NOSETUP shift/scroll indicators

                                   NOINDICATORS

 

 

To omit any one or combination of the above, first #define the appropriate

literal in your application, then #include the stubs file. This need only be

done once, for instance in the application's main routine. For example, if the

application is not going to use scrolling fields, the scrolling functions could

be omitted, and the application source might look like the following:

 

#define NOSCROLL

#include "smdefs.h"

#include "sm_stubs.c"

 

main ()

{

     /* ...the application code... */

}

 

The effect of defining the literal and including sm_stubs.c is to declare stub

routines in the application; this causes the linker not to add the real routines

from the screen manager library to the application. The bulk of the savings will

be in code space. The stubbing technique does not work on systems where the

library is itself a linked entity, such as a shareable library.

 

If range, math, and JPL support are all stubbed out, you can also omit linking

the C math library (-lm flag on UNIX systems, math library on MS-DOS systems).

 


 

 

 

 

 

 

 

                                        Index

 

 

 

 

             In  this  Index, library functions  are  displayed  in

             boldface,   without  the  prefixes  specific  to   the

             language  interface.  Video  and  setup  file  entries

             appear in ELITE CAPS, while utility  programs  and JPL

             commands  are in elite lower-case. Function key  names

             are in ROMAN CAPS.

 

 

 

 

        1clear_array 3-11, 3-18             beep 3-30, 3-55, 3-72, 3-76,

        1protect 3-15, 3-19, 3-20,               3-162

             3-25, 3-27, 3-83, 3-158        bel 3-15, 3-30, 3-55, 3-72,

        1unprotect 3-15, 3-19, 3-20,             3-76, 3-162

             3-220                          BELL video parameter 3-30

                                            bin2c utility 3-51, 3-53,

        A                                        3-57, 3-113, 3-222,

        a_bitop 3-31                             3-253, 3-254

        ABORT key 3-87, 3-104, 3-247        bitop 3-4, 3-5, 3-15, 3-31

        achg 3-11, 3-21, 3-42               BUFSIZ video parameter 3-67

        allget 3-13, 3-23, 3-251

        amount field 3-193                  C

        amt_format 3-11, 3-24, 3-66,        c_off 3-12, 3-33

             3-68, 3-93, 3-144,             c_on 3-12, 3-34

             3-149                          c_vis 3-12, 3-35, 3-56,

        APP1 key 3-247                           3-73, 3-77, 3-138,

        application                              3-163, 3-213, 3-248

           efficiency 3-253                 calc 3-11, 3-36, 3-186

           international 3-253              cancel 3-10, 3-37

           main routine 3-7                 case sensitivity 3-78, 3-134

           space saving 3-255               ch_emsgatt 3-14, 3-38, 3-76

        application Portability             ch_form_atts 3-14, 3-39

             3-252                          ch_qmsgatt 3-14, 3-40, 3-161

        aprotect 3-15, 3-19, 3-20,          ch_stextatt 3-14, 3-41

             3-25, 3-27, 3-158              ch_umsgatt 3-14

        array                               ch_umsgatts 3-218

           size of 3-190                    chg_attr 3-11, 3-21, 3-42

        ascroll 3-14, 3-26                  choice 3-12, 3-16, 3-43,

        asynchronous function 3-200              3-104, 3-252

        attached function 3-3               ckdigit 3-203

           parameters 3-3                   cl_all_mdts 3-15, 3-45

           return value 3-4                 cl_everyfield 3-11, 3-46

        aunprotect 3-15, 3-25, 3-27,        cl_unprot 3-11, 3-47

             3-220                          CLEAR ALL key 3-47

                                            clear_array 3-11, 3-14,

        B                                        3-18, 3-48

        background status 3-248             close_window 3-5, 3-6, 3-9,

        BACKSPACE key 3-154                      3-11, 3-49

        backtab 3-12, 3-28                  COF video parameter 3-33,

        BACKTAB key 3-3, 3-4, 3-135,             3-34

             3-153, 3-154                   CON video parameter 3-33,

        base_fldno 3-15, 3-29                    3-34


 

        configuration

           determination at runtime         E

             3-244                          e_ 3-9, 3-14

        configuration files 3-244           e_1protect 3-67

           memory-resident 3-254            e_1unprotect 3-67

        control path 3-237, 3-238,          e_amt_format 3-67, 3-68

             3-239                          e_bitop 3-67

        control string 3-1                  e_chg_attr 3-67

           target list 3-1                  e_dblval 3-67

        control strings 3-1                 e_dlength 3-67

        CURPOS video parameter 3-35         e_dtofield 3-67

        cursor                              e_fldno 3-68, 3-69

           locating 3-189                   e_fptr 3-68

           position 3-85                    e_fval 3-68

           position display 3-35            e_getfield 3-68

           turn off 3-33                    e_gofield 3-68

           turn on 3-34                     e_intval 3-68

        cursor motion 3-90, 3-92,           e_is_yes 3-68

             3-123, 3-146, 3-198            e_itofield 3-68

           control 3-152                    e_lngval 3-68

        cursor style 3-204                  e_ltofield 3-68

                                            e_mdt_clear 3-68

        D                                   e_mod_test 3-68

        d_ 3-10, 3-16                       e_novalbit 3-68

        d_at_cur 3-11, 3-51                 e_off_gofield 3-68

        d_form 3-5, 3-11, 3-53,             e_protect 3-68

             3-253                          e_putfield 3-68

        d_msg_line 3-13, 3-55, 3-72,        e_unprotect 3-68

             3-76, 3-132, 3-138,            edit_ptr 3-12, 3-70, 3-186,

             3-143, 3-161, 3-162,                3-192, 3-250

             3-164, 3-187, 3-188,           8-bit ASCII 3-253

             3-213, 3-248                   element number 3-68

        d_window 3-6, 3-11, 3-57,           emsg 3-13, 3-72, 3-74, 3-76,

             3-165, 3-167, 3-232                 3-162, 3-248

        data dictionary                     environment

           and LDB 3-251                       system 3-244

        data length 3-63                       use at startup 3-244

        data links 3-251                    environment variables 3-255

        data structure access 3-171,        environment variables: see SMKEY,

             3-172, 3-225, 3-228                 SMVARS, etc.

        dblval 3-13, 3-59                   er_options 3-14, 3-72, 3-74,

        dd2struct utility 3-179,                 3-76, 3-162, 3-164

             3-224                          ERASE key 3-154

        dd_able 3-14, 3-23, 3-60,           err_reset 3-9, 3-13, 3-14,

             3-251                               3-38, 3-55, 3-72, 3-74,

        delayed write 3-67, 3-247                3-76, 3-164, 3-187,

        DELETE CHAR key 3-87                     3-188, 3-248

        DELETE LINE key 3-65                error message 3-76, 3-161,

        dicname 3-14, 3-61, 3-125                3-164, 3-245

        disp_off 3-12, 3-62, 3-189             translation 3-253

        display attribute                   EXIT key 3-1, 3-2, 3-43,

           embedded in status line               3-49, 3-51, 3-57, 3-87,

             3-55, 3-72, 3-76, 3-162             3-91, 3-115, 3-120,

           of field 3-42                         3-134, 3-154, 3-165,

           of inquiries 3-40                     3-169, 3-237, 3-252

           of messages 3-38                 exit processing 3-174

           of prompts 3-41

           of windows 3-39                  F

        dlength 3-13, 3-63, 3-127           f2struct utility 3-171,

        do_region 3-15, 3-64                     3-172, 3-225, 3-228,

        doccur 3-11, 3-65, 3-102                 3-230

        dtofield 3-11, 3-66                 fcase 3-78

        dw_options 3-14, 3-67               fextension 3-10, 3-79


 

        field                                  TRANSMIT, 3-91

           changing display                    TRANSMIT. 3-91

             attribute 3-42                    XMIT 3-1

           current 3-85                        ZOOM 3-234

           date 3-186                       function key labels 3-55,

           time 3-192                            3-72, 3-76, 3-162

        field length 3-127                  function keys

        field name 3-144, 3-145                labeling 3-122

        field number 3-85, 3-145               routing of 3-247

        field validation 3-147,                undefined 3-246

             3-182                          function list 3-1, 3-7

           order of 3-182                   fval 3-3, 3-4, 3-15, 3-83

        flush 3-15, 3-80, 3-132,

             3-173, 3-208, 3-232,           G

             3-247                          getcurno 3-12, 3-85

        foreign language support            getfield 3-12, 3-16, 3-63,

             3-253                               3-82, 3-86, 3-159,

        form list 3-254                          3-232

        formlib utility 3-115,              getkey 3-10, 3-11, 3-12,

             3-118, 3-119, 3-120                 3-17, 3-87, 3-89,

        formlist 3-10, 3-51, 3-53,               3-104, 3-111, 3-154,

             3-57, 3-81, 3-178,                  3-173, 3-200, 3-202,

             3-254                               3-204, 3-205, 3-208,

        fptr 3-12, 3-16, 3-43, 3-82,             3-212, 3-219, 3-246

             3-103                          gofield 3-9, 3-12, 3-90

        function key                        graphics characters 3-247,

           ABORT 3-87, 3-104, 3-247              3-253

           APP1 3-247                       graphics modes 3-247

           BACKSPACE 3-154                  GRTYPE video parameter 3-253

           BACKTAB 3-3, 3-4, 3-135,         gtchar 3-200

             3-153, 3-154

           CLEAR ALL 3-47                   H

           DELETE CHAR 3-87                 HELP key 3-87, 3-91, 3-154

           DELETE LINE 3-65                 help screen 3-91

           ERASE 3-154                      hlp_by_name 3-11, 3-15, 3-91

           EXIT 3-1, 3-2, 3-43,             home 3-12, 3-92, 3-123

             3-49, 3-51, 3-57, 3-87,        HOME key 3-4

             3-91, 3-115, 3-120,            hook

             3-134, 3-154, 3-165,              field attachment 3-3

             3-169, 3-237, 3-252               invoked function 3-1

           HELP 3-87, 3-91, 3-154

           HOME 3-4                         I

           INSERT 3-87, 3-154, 3-204        i_ 3-9

           INSERT LINE 3-102                i_achg 3-21, 3-93

           LOCAL PRINT 3-87, 3-91,          i_amt_format 3-93

             3-154                          i_bitop 3-31, 3-93

           PAGE DOWN 3-16                   i_dblval 3-93

           PAGE UP 3-16, 3-154              i_dlength 3-93

           PF1 3-1, 3-87, 3-247             i_doccur 3-93

           PF10 3-239, 3-242                i_dtofield 3-93

           PF24 3-87                        i_fptr 3-93

           RESCREEN 3-87, 3-91,             i_fval 3-93

             3-154, 3-173                   i_getfield 3-93

           RETURN 3-3, 3-146, 3-153         i_gofield 3-90, 3-93

           SPF1 3-87, 3-238, 3-247          i_intval 3-93

           SPF2 3-39, 3-242                 i_ioccur 3-93, 3-102

           SPF24 3-87                       i_itofield 3-93

           SPF3 3-39, 3-239                 i_lngval 3-93

           TAB 3-3, 3-135, 3-153,           i_ltofield 3-93

             3-154, 3-198                   i_mdt_clear 3-93

           TRANSMIT 3-2, 3-3, 3-4,          i_mod_test 3-93

             3-43, 3-87, 3-134,             i_novalbit 3-93

             3-154, 3-182, 3-241,           i_off_gofield 3-93

             3-242                          i_putfield 3-93, 3-159

        inbusiness 3-94                     keyfilter 3-14, 3-111

        ind_set 3-15, 3-95                  keyhit 3-12, 3-112, 3-202

        inictrl 3-10                        keyinit 3-10, 3-113, 3-245

        INICTRL setup variable 3-160        keylabel 3-15, 3-114

        ininames 3-96, 3-125, 3-129         keys

        initcrt 3-9, 3-10, 3-37,               cursor motion 3-135

             3-81, 3-94, 3-97,              keytops 3-55, 3-72, 3-76,

             3-113, 3-119, 3-141,                3-162

             3-165, 3-167, 3-174,           KPAR video parameter 3-122

             3-191, 3-214, 3-222,           KSET video parameter 3-122

             3-244, 3-245, 3-248

        INSERT key 3-87, 3-154,             L

             3-204                          l_ 3-10, 3-16

        INSERT LINE key 3-102               l_at_cur 3-11, 3-115

        INSOFF video parameter 3-204        l_close 3-11, 3-117

        INSON video parameter 3-204         l_form 3-11, 3-118

        install 3-7, 3-10, 3-87,            l_open 3-11, 3-115, 3-117,

             3-97, 3-98, 3-99,                   3-118, 3-119, 3-120

             3-200, 3-203, 3-204,           l_window 3-11, 3-119, 3-120,

             3-205, 3-213, 3-214,                3-165, 3-167

             3-215, 3-216, 3-250            label_key 3-15, 3-122

        international applications          last 3-12, 3-123

             3-253                          lclear 3-11, 3-124, 3-125

        intval 3-13, 3-101                  LDB 3-23, 3-251

        invoked function 3-1                   write-through 3-60, 3-251

           chaining 3-1                     LDB merge 3-23

           parameters 3-1                   ldb_init 3-11, 3-61, 3-96,

           return value 3-1                      3-125, 3-252

           target list 3-1                  leave 3-10, 3-94, 3-126,

        ioccur 3-11, 3-65, 3-102                 3-173, 3-177

        is_yes 3-13, 3-103                  length 3-15, 3-127

        isabort 3-12, 3-87, 3-104           library functions

        item_id 3-14                           categories 3-10

        itofield 3-11, 3-105                   naming conventions 3-9

                                               stubs 3-255

        J                                      typical use 3-9

        jam_auto 3-5                        lngval 3-13, 3-128

        jam_menu 3-241                      LOCAL PRINT key 3-87, 3-91,

        jclose 3-106                             3-154

        jform 3-107                         logical keys 3-245, 3-246

        ^jm_exit 3-237, 3-238               lreset 3-11, 3-96, 3-125,

        ^jm_goform 3-239                         3-129, 3-251

        ^jm_gotop 3-238                     lstore 3-13, 3-49, 3-130,

        ^jm_keys 3-240                           3-251, 3-252

        ^jm_mnutogl 3-241                   ltofield 3-11, 3-131

        ^jm_system 3-242

        ^jpl 3-243                          M

        jwindow 3-109                       m_flush 3-15, 3-132

                                            math edit 3-36

        K                                   max_occur 3-15, 3-133, 3-148

        key processing 3-245                MDT bit 3-3, 3-4, 3-5, 3-23,

        key routing 3-154                        3-45, 3-159, 3-199,

           algorithm 3-246                       3-251

           to change 3-247                  memo edits 3-70, 3-250

        key translation                     memory-resident

           algorithm 3-245                     configuration files 3-254

           initialization 3-113                screen 3-51

        key translation file 3-55,             screens 3-253

             3-72, 3-76, 3-162              menu 3-43

        key2bin utility 3-113                  cursor motion control

        keyboard input 3-87, 3-112,              3-135

             3-152, 3-154                   MENU bit 3-43, 3-91, 3-241

        keyboard mapping: see key           menu_proc 3-10, 3-12, 3-14,

             translation                         3-16, 3-17, 3-43,

             3-134, 3-135, 3-137,           o_achg 3-21, 3-149

             3-241, 3-252                   o_amt_format 3-149

        message file 3-248                  o_bitop 3-31, 3-149

        modkey utility 3-245                o_chg_attr 3-149

        mp_options 3-14, 3-43,              o_dblval 3-149

             3-134, 3-135, 3-152            o_dlength 3-149

        mp_string 3-14, 3-16, 3-43,         o_doccur 3-149

             3-134, 3-137                   o_dtofield 3-149

        MS-DOS 3-256                        o_fptr 3-149

        msg 3-13, 3-138, 3-248              o_fval 3-149

        msg2bin utility 3-139               o_getfield 3-149

        msg_get 3-13, 3-139, 3-140,         o_gofield 3-90, 3-149

             3-141, 3-142, 3-248            o_intval 3-149

        msgfind 3-13, 3-140, 3-141,         o_ioccur 3-102, 3-149

             3-142                          o_itofield 3-149

        msginit 3-244                       o_lngval 3-149

        msgread 3-10, 3-139, 3-141,         o_ltofield 3-149

             3-255                          o_mdt_clear 3-149

        mwindow 3-13, 3-143                 o_mod_test 3-149

                                            o_novalbit 3-149

        N                                   o_off_gofield 3-149

        n_ 3-9                              o_putfield 3-149

        n_1clear_array 3-144                occur_no 3-15, 3-150

        n_1protect 3-144                    occurrence 3-149

        n_1unprotect 3-144                  occurrence number

        n_amt_format 3-144                     obtaining 3-150

        n_aprotect 3-144                    off_gofield 3-12, 3-90,

        n_aunprotect 3-144                       3-151

        n_bitop 3-144                       offscreen data 3-18

        n_chg_attr 3-144                    ok_options 3-3, 3-14, 3-97,

        n_clear_array 3-144                      3-135, 3-152, 3-154

        n_dblval 3-144                      op_mdt 3-199

        n_dlength 3-144                     openkeybd 3-3, 3-5, 3-9,

        n_dtofield 3-144                         3-10, 3-12, 3-14, 3-17,

        n_edit_ptr 3-144                         3-83, 3-104, 3-152,

        n_fldno 3-15, 3-144, 3-145               3-154, 3-182, 3-241,

        n_fptr 3-144                             3-246

        n_fval 3-144                        oshift 3-14, 3-156

        n_getfield 3-144

        n_gofield 3-144                     P

        n_intval 3-144                      PAGE DOWN key 3-16

        n_is_yes 3-144                      PAGE UP key 3-16, 3-154

        n_itofield 3-144                    PF1 key 3-1, 3-87, 3-247

        n_length 3-144                      PF10 key 3-239, 3-242

        n_lngval 3-144                      PF24 key 3-87

        n_ltofield 3-144                    pkptr 3-12, 3-16

        n_max_occur 3-144                   plcall 3-15, 3-157

        n_mdt_clear 3-144                   portability 3-252

        n_mod_test 3-144                    program initialization 3-244

        n_novalbit 3-144                    prompt 3-55, 3-72, 3-76,

        n_num_items 3-144                        3-162

        n_off_gofield 3-144                 protect 3-15, 3-19, 3-20,

        n_protect 3-144                          3-25, 3-27, 3-158

        n_putfield 3-144, 3-159             PROTECT bits 3-158, 3-220

        n_size_of_array 3-144               protected field 3-158, 3-220

        n_unprotect 3-144                   putfield 3-3, 3-5, 3-9,

        n_wselect 3-144, 3-232                   3-11, 3-24, 3-45, 3-86,

        nl 3-12, 3-146                           3-147, 3-148, 3-159,

        novalbit 3-15, 3-147                     3-232

        num_items 3-14                      putjctrl 3-15, 3-160

        num_occurs 3-12, 3-148

 

        O

        o_ 3-9

                                            screen validation 3-182

        Q                                   scroll 3-181

        query_msg 3-12, 3-13, 3-14,         scrolling array 3-48

             3-40, 3-161, 3-187,               maximum item count 3-133,

             3-248                               3-185

        qui_msg 3-13, 3-72, 3-74,           scrolling field

             3-162, 3-164, 3-248               number of items in 3-148

        quiet_err 3-13, 3-14, 3-38,         sdate 3-15, 3-186

             3-74, 3-76, 3-162,             setbkstat 3-13, 3-187,

             3-164, 3-187, 3-248                 3-188, 3-248

                                            setstatus 3-14, 3-55, 3-187,

        R                                        3-188, 3-248

        r_ 3-9, 3-16                        SETUP video parameter 3-177

        r_at_cur 3-11, 3-51, 3-53,          sh_off 3-15, 3-62, 3-189

             3-57, 3-81, 3-143,             size_of_array 3-15, 3-190

             3-165                          sm_do_not_display 3-170,

        r_form 3-5, 3-9, 3-11, 3-81,             3-173

             3-167                          SMCHEMSGATT setup variable

        r_window 3-5, 3-9, 3-11,                 3-38

             3-78, 3-79, 3-81, 3-97,        SMCHFORMATTS setup variable

             3-115, 3-118, 3-119,                3-39

             3-120, 3-169, 3-178,           SMCHQMSGATT setup variable

             3-251, 3-253                        3-40

        rd_part 3-13, 3-171, 3-225          SMCHSTEXTATT setup variable

        rdstruct 3-13, 3-171, 3-172,             3-41

             3-179, 3-225                   SMDICNAME setup variable

        rescreen 3-11, 3-15, 3-173,              3-61

             3-177, 3-255                   SMDWOPTIONS setup variable

        RESCREEN key 3-87, 3-91,                 3-67

             3-154, 3-173                   SMEROPTIONS setup variable

        RESET video parameter 3-126,             3-74

             3-174                          SMFCASE setup variable 3-254

        resetcrt 3-9, 3-10, 3-37,           SMFEXTENSION setup variable

             3-94, 3-174, 3-215                  3-79, 3-254

        resize 3-15, 3-175                  SMFLIBS setup variable 3-16,

        restore_data 3-13, 3-176,                3-119

             3-180, 3-184, 3-194            SMINDSET setup variable 3-95

        return 3-10, 3-94, 3-177            SMINICTRL setup variable

        RETURN key 3-3, 3-146, 3-153             3-238

        rmformlist 3-10, 3-178              SMININAMES setup variable

        routing table 3-154                      3-96

        rrecord 3-13, 3-179, 3-224          SMKEY setup variable 3-113,

        rs_data 3-13, 3-180, 3-194               3-244

        rscroll 3-14, 3-181                 SMMPOPTIONS setup variable

                                                 3-135

        S                                   SMMPSTRING setup variable

        s_val 3-3, 3-4, 3-15, 3-182              3-137

        sample programs 3-8                 SMMSGS setup variable 3-141,

        save_data 3-13, 3-176,                   3-244

             3-184, 3-195                   SMOKOPTIONS setup variable

        sc_max 3-14, 3-102, 3-133,               3-153

             3-185                          SMPATH setup variable 3-61,

        screen                                   3-97, 3-119, 3-129,

           memory-resident 3-253                 3-157, 3-165, 3-167

             display 3-51, 3-53,            smsetup 3-10, 3-191, 3-221

             3-57                           SMSETUP setup variable 3-97,

        screen display 3-165, 3-167,             3-191, 3-244

             3-169                          SMTERM setup variable 3-97,

        screen entry function 3-5                3-244

        screen initialization 3-97          SMUSEEXT setup variable 3-79

        screen library 3-115, 3-117,        SMVAGS  setup variable 3-97

             3-118, 3-119, 3-120            SMVARS setup variable 3-191,

        screen output                            3-244, 3-255

           optimization 3-255

        SMVIDEO setup variable              u_ckdigit 3-98, 3-203, 3-249

             3-222, 3-244                   u_inscrsr 3-98, 3-204, 3-249

        SMZMOPTIONS setup variable          u_keychange 3-87, 3-249

             3-235                          u_keychg 3-98, 3-205

        special edits 3-70                  u_play 3-87, 3-98, 3-202,

           check digit 3-203                     3-205, 3-208, 3-212,

        SPF1 key 3-87, 3-238, 3-247              3-249

        SPF2 key 3-39, 3-242                u_record 3-87, 3-98, 3-202,

        SPF24 key 3-87                           3-208, 3-212, 3-249

        SPF3 key 3-39, 3-239                u_statfnc 3-98, 3-213, 3-249

        status line 3-55, 3-76,             u_uinit 3-97, 3-98, 3-214,

             3-138, 3-161, 3-164,                3-244, 3-249, 3-250

             3-187, 3-213, 3-248            u_ureset 3-98, 3-215, 3-249,

           embedded attribute 3-55,              3-250

             3-72, 3-76, 3-162              u_vproc 3-98, 3-216, 3-249

        status text 3-55, 3-72,             ungetkey 3-12, 3-87, 3-212,

             3-76, 3-162                         3-219, 3-240

        status window 3-55, 3-72,           UNIX 3-256

             3-76, 3-162                    unprotect 3-220

        stime 3-15, 3-192                   unsetup 3-10, 3-191, 3-221

        strip_amt_ptr 3-12, 3-59,

             3-193                          V

        stub functions 3-255                VALIDED bit 3-3, 3-4, 3-147,

        sv_data 3-13, 3-180, 3-194,              3-159

             3-195                          var2bin utility 3-244

        sv_free 3-184, 3-195                vid2bin utility 3-222

                                            vinit 3-10, 3-97, 3-222,

        T                                        3-245

        t_bitop 3-31

        t_scroll 3-14, 3-196                W

        t_shift 3-14, 3-197                 wdeselect 3-11, 3-223, 3-232

        tab 3-12, 3-83, 3-198               window 3-49, 3-57

        TAB key 3-3, 3-135, 3-153,             display 3-165, 3-169

             3-154, 3-198                   wrecord 3-13, 3-179, 3-224

        target list 3-1                     wrt_part 3-13, 3-171, 3-225

        TERM 3-244                          wrtpart 3-225

        terminal dependencies 3-252         wrtstruct 3-13, 3-171,

        terminal setup 3-245                     3-172, 3-225, 3-228

        TRANSMIT key 3-2, 3-3, 3-4,         wselect 3-11, 3-51, 3-57,

             3-43, 3-87, 3-134,                  3-109, 3-115, 3-120,

             3-154, 3-182, 3-241,                3-165, 3-169, 3-223,

             3-242                               3-232

        TRANSMIT, key 3-91

        TRANSMIT. key 3-91                  X

        tst_all_mdts 3-15, 3-199            XMIT key 3-1

 

        U                                   Z

        u_async 3-98, 3-200, 3-249          zm_options 3-14, 3-234

        u_avail 3-98, 3-202, 3-208,         ZOOM key 3-234

             3-212, 3-249