# PAL - Quickreference: Sm_svc

## System Manager Access

This is a sub-set of the HP System Manager functions that can be successfully called from non-SysMgr compliant DOS programs. (i.e. PAL programs)

Note that your application should check first wether SysMgr is loaded before actually calling functions of this module. You can test for the presence of SysMgr using the CheckSysMgr function from the MISC module.

Available functions:

[sound services]
m_play : Play a sound string in HP alarm sound format.
m_sound : Generate one of several sound patterns.
m_soundoff : Turns off sounds generated by m_asound.

[clipboard services]
m_open_cb : Claim access to the clipboard and lock it.
m_cb_read : Read data from clipboard.
m_cb_write : Write data to clipboard.
m_fini_rep : Terminate writing to clipboard.
m_close_cb : Release the clipboard to other applications.

m_new_rep : Prepare sending a new 'representation'.
m_rep_index : Get info about a representation.
m_reset_cb : Clear clipboard, get ownership.
m_get_cb_info : Get clipboard state info.

[Task Control Block access]
m_get_TCB : Get Task Control Block.
m_get_TCB_size : Get Task Control Block size.
IsAppActive : Check if a specified application is active.

[Miscellaneous]
SerialCtl : control SysMgr serial port interference

SEE ALSO: CheckSysMgr

## Sound Services

## m_play

NAME

            m_play

DESCRIPTION

            Play a sound character string in the HP alarm sound format.

SYNOPSIS

            #include "palsmsvc.h"
            void m_play( sound_string );

INPUTS

            sound_string  - an ASCII string terminated by a carriage
                            return or zero, comprised of any legal play
                            commands in the list below

SAMPLE

            void main (void)
            {
               char *Tune = "V3K1T230L8MNO3"
                            "E..CDECDE F..DEFDEF"
                            "G...A.. EFG MS D. MNDEGE.DL4C";

               m_play(Tune);

SEE ALSO
  Commands m_asound m_soundoff

## Commands

m_play Commands: A - G Play appropriate musical note in current octave, length and tempo. May be immediately followed by a "+" or "#" to indicate a sharp, or a "-" to indicate a flat note. K Enable user termination if keystroke entered. Default is user termination enabled. Range 0-1. A value of 1 indicates user termination enabled. L Length of note. Range 1-64, where 64 = 1/8 note, 32 = 1/4 note, etc. Default = 8 (whole note). M Music play style. Default = N. Range: N - Normal L - Legato 8 - Staccato O Octave. Sets the current octave for all subsequent notes. Default = 4. Range 0-7. P Pause. Pause between notes. Range 1-64. Length of pause is determined in the same manner as the length of note (L). T Tempo (pace of music). A higher value indicates a faster pace. Range 0-255. Default = 160. V Set speaker volume. Range 0-3. 3 is loudest. ;(semicolon) Used to separate music for readability. (space) Used to separate music for readability. ,(comma) Used to separate music for readability. .(period) Extend a note's play time by a factor of 1.5.
SEE ALSO
  m_play

  ## m_asound

  NAME

              m_asound

  DESCRIPTION

              Generate one of ten sound patterns as specified by index. Sounds
              0 thru 4 roughly match those generated by 1-2-3.  Sounds 5 thru
              9 are more involved sounds.

  SYNOPSIS

              #include "palsmsvc.h"
              void m_asound( int index );

  INPUTS

              index  - an integer representing the sound to be made.

  SAMPLE

              void main (void)
              {
                 m_asound( 1 );
              }

  NOTE

              Sounds generated by m_asound may be terminated by calling
              m_soundoff.

  SEE ALSO
    m_soundoff

  ## m_soundoff

  NAME

              m_soundoff

  DESCRIPTION

              Turns off sounds generated by m_asound.

  SYNOPSIS

              #include "palsmsvc.h"
              void m_asound( void );

  SAMPLE

              void main (void)
              {
                 m_asound( 1 );
                 m_soundoff();
              }

  NOTE

              If the speaker is on when this function is called, the sound
              will not end until the next clock tic

  SEE ALSO
    m_asound

  ## Task Control Block access

  ## m_get_TCB

  NAME

              m_get_TCB

  DESCRIPTION

              This function returns a far pointer pointing to the address
              of the TCB block array. A TCB (Task Control Block) is used
              by System Manager to track all the SysMgr compliant
              applications in memory. It contains information about the
              application name, its hotkey, as well the SP, IP and the
              ROM bank of the application, necessary for the SysMgr to
              be able to swap to an application.

  SYNOPSIS

              #include "palsmsvc.h"
              task far* m_get_TCB(void);

  INPUTS

              None.

  RETURNS

              Far pointer to a "task" structure, described below.

  NOTE

              System Manager must be loaded before you can use this
              function, otherwise a crash will occur. You can check
              if SysMgr is running by using the CheckSysMgr() function.

              Here is the definition of the "task" structure:

            /* TASK CONTROL BLOCK structure */
            struct task {
                unsigned  t_sp;             /* offset made low, mdb     */
                unsigned  t_ss;
                unsigned  t_off_image;      /* offset made low, mdb     */
                unsigned  t_seg_image;
                unsigned  t_ds;
                unsigned  t_memseg;         /* base of allocation block */
                unsigned  t_hotkey;         /* copied from IMAGEVEC     */

                unsigned  t_phypage[2];     /* IMAGEVEC.wAS_PhyPage     */
                unsigned  t_logicalpage[2]; /* IMAGEVEC.wRS_LogicalPage */
                unsigned  t_pagecount[2];   /* IMAGEVEC.wRS_PageCount   */
                char      t_chipsel[2];
                char      t_state;
                char      t_is123;
                unsigned  t_rsrc_seg;
                char      t_nowait;
                char      t_sys_ver;
                char      t_extname[12];
                char      t_lock_state;
                char      t_spare[3];
                unsigned  t_far_size;
                unsigned  t_far_off;
                unsigned  t_far_rsvrd;
                char      t_sp_status;
                char      t_sp_link;
                unsigned  t_ic_u_loc;
                unsigned  t_ic_o_loc;
           };

  SAMPLE

              #include "pal.h"
              #include "palsmsvc.h"

              void main(void) {

                 unsigned int i, size;
                 struct task far *pTCB;     /* TCB pointer */

                 if(!CheckSysMgr()) FatalExit("SysMgr not loaded.", 1);

                 pTCB = m_get_TCB();        /* get TCB address */
                 size = (int)m_get_TCB_size();   /* get TCB size */

                 printf("TCB = %08lX, size = %d\n", pTCB, size);

                 /* Display the TCB entries one by one */
                 for(i = 0; i < size; i++) {
                    char far *s;

                    /* print index, hotkey & name of the active applications */
                    printf("Index: %d  Hotkey: 0x%04X  ", i, pTCB->t_hotkey);
                    printf("Name:");
                    for(s = &pTCB->t_extname[0]; *s; ++s) putchar(*s);
                    printf("\n");
                    pTCB++;
                 }
              }

  SEE ALSO
    m_get_TCB_size IsAppActive

  ## m_get_TCB_size

  NAME

              m_get_TCB_size

  DESCRIPTION

              Returns the size (number of active applications) of the Task Control
              Block structure. A TCB (Task Control Block) is used by System Manager
              to track all the SysMgr compliant applications in memory.
              It contains information about the application name, its hotkey,
              as well the SP, IP and the ROM bank of the application,
              necessary for the SysMgr to be able to swap to an application.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_get_TCB(void);

  INPUTS

              None.

  RETURNS

              Returns the number of entries in the TCB block.

  NOTE

              System Manager must be loaded before you can use this
              function, otherwise a crash will occur. You can check
              if SysMgr is running with the CheckSysMgr() function.
              Take a look at the get_TCB() function for more details.

  SAMPLE

              See the get_TCB function.

  SEE ALSO
    m_get_TCB IsAppActive

  ## IsAppActive

  NAME

              IsAppActive

  DESCRIPTION

              This function can be used to check if a specified SysMgr
              application is active while SysMgr is running.

  SYNOPSIS

              #include "palsmsvc.h"
              int IsAppActive(WORD KeyCode);

  INPUTS

              KeyCode : An integer specifying the hotkey scan key code which
                        activates the application. Use the following constants
                        for the keycodes of the built-in apps:

                        APPMGR_KEY, SETUP_KEY, FILER_KEY, DBASE_KEY,
                        CALC_KEY, APPT_KEY, LOTUS_KEY, PHONE_KEY, NOTE_KEY,
                        MEMO_KEY, DATACOMM_KEY, QUICKEN_KEY, MACROS_KEY,
                        WORLD_KEY, WATCH_KEY, CCMAIL_KEY, DOS_KEY.

  RETURNS

              Returns TRUE if the application is active, FALSE otherwise.

  NOTE

              This function checks if the SysMgr is active, so there's
              no need to do so before calling it. It will return FALSE
              if the application is closed or SysMgr is not loaded.

  SAMPLE

           /* Check if the phonebook application is active */
           if(IsAppActive(0xB400)==TRUE)
              printf("Phonebook Application is active.\n");

  SEE ALSO
    m_get_TCB m_get_TCB_size

  ## Clipboard Management Services

  ## m_cb_read

  NAME

              m_cb_read

  DESCRIPTION

              Reads "size" bytes of data to "buffer" from the representation
              associated with "index".  "offset" indicates the starting
              offset in the clipboard buffer where the read will begin.
              Multiple calls can be made to allow reading of all data.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_cb_read( int index, unsigned offset, char *buffer,
                             unsigned size );

  INPUTS

              int index         Index number of representation to be read
                                obtained from m_rep_index.
              unsigned offset   Offset into data where transfer will begin.
              char *buffer      Pointer to area to receive data.
              unsigned size     Maximum amount of data to transfer.  Cannot
                                exceed 1024 bytes per call.

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied
              CB_NO_SUCH        The specified representation is not there.
              CB_BOUNDS         The offset points past the end of the data.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_cb_write

  NAME

              m_cb_write

  DESCRIPTION

              Writes "length" bytes from "data" to the representation
              previously opened by m_new_rep.  Multiple calls can be made
              to append data to a single representation.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_cb_write( char *data, unsigned length );

  INPUTS

              char *data        Pointer to data to be written.
              unsigned length   Length of data to be written.  Cannot exceed
                                1024 bytes per call.

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied.
              CB_NO_REP         No representation is currently open.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_close_cb

  NAME

              m_close_cb

  DESCRIPTION

              Releases the clipboard for access by other applications

  SYNOPSIS

              #include "palsmsvc.h"
              int m_close_cb();

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied.
              CB_REP_OPEN       Current representation is not finished.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_fini_rep

  NAME

              m_fini_rep

  DESCRIPTION

              Tells the clipboard that no additional data will be sent for
              the current representation.  Closes the representation and
              terminates write access to the clipboard.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_fini_rep();

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied.
              CB_NO_REP         No representation is currently open.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_get_cb_info

  NAME

              m_get_cb_info

  DESCRIPTION

              Retrieves information on the current state of the clipboard

  SYNOPSIS

              #include "palsmsvc.h"
              int m_get_cb_info( int *count, char *author, unsigned *cbsize,
                                 unsigned cbsize_inuse );

  INPUTS

              int *count        Number of representations in the clipboard
              char *author      String identifying the author of the
                                clipboard's current contents.  (48 bytes max).
              unsigned *cbsize  Size of the clipboard in bytes
              unsigned *cbsize_inuse    Amount of the clipboard in use, in
                                bytes, including the header.

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_new_rep

  NAME

              m_new_rep

  DESCRIPTION

              Prepares the clipboard to receive a representation under the
              name, "rep_name", or appends data to an existing
              representation.  Multiple representations of the same data may
              be copied to the clipboard.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_new_rep( char *rep_name );

  INPUTS

              char *rep_name    Name for the new representation

  RETURNS

              CB_OK             Successful call.
              CB_EXISTS         The representation already exists.
              CB_REP_OPEN       Another representation is already open.
              CB_ALLOC          No space for the new representation.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_open_cb

  NAME

              m_open_cb

  DESCRIPTION

              Claims the clipboard, if available.  Sets an "in use" flag to
              lock out claim requests from other applications.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_open_cb();

  RETURNS

              CB_OK             Successful call.
              CB_LOCKED         The clipboard is already in use.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_rep_index

  NAME

              m_rep_index

  DESCRIPTION

              Obtains the index number and length of the representation
              specified by "name".  The index number and length are used by
              m_cb_read.

  SYNOPSIS

              #include "palsmsvc.h"
              int m_rep_index( char *name, int *index, unsigned *length );

  INPUTS

              char *name        Name of the representation. "TEXT" is the
                                default.
              int *index        Index number of specified representation.
              unsigned *length  Length in bytes of the specified
                                representation.

  RETURNS

              CB_OK             Successful call.
              CB_NO_SUCH        The specified representation is not there.
              CB_NOT_OPEN       Clipboard access is denied.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## m_reset_cb

  NAME

              m_reset_cb

  DESCRIPTION

              Clears the contents of the clipboard and establishes the
              current application, specified by "author" as the creator of
              clipboard contents.  Each application should use a unique
              string for "author".

  SYNOPSIS

              #include "palsmsvc.h"
              int m_reset_cb( char *author );

  INPUTS

              char *author      Author Name to be set in clipboard header

  RETURNS

              CB_OK             Successful call.
              CB_NOT_OPEN       Clipboard access is denied.
              CB_ALLOC          Memory manager cannot reset clipboard size.

  SAMPLE

             See cbcp.c

  SEE ALSO
    cbcp.c

  ## Clipboard Status

  Clipboard Status Clipboard service functions return status codes indicating action. The names used are as defined in palsmsvc.h

              CB_OK          0   Success
              CB_LOCKED     -1   Clipboard access denied
              CB_NOT_OPEN   -2   Clipboard not formally open
              CB_ALLOC      -3   Heap allocation failure
              CB_EXISTS     -4   Representation already exists
              CB_REP_OPEN   -5   A representation is open
              CB_NO_REP     -6   No representation open
              CB_NO_SUCH    -7   No such representation
              CB_BOUNDS     -8   Transfer request out of bounds

  ## cbcp.c

      /* --------------------------------------------------------------------
         Project: Clipboard test program
         Module:  cbcp.c
         Author:  Ron Crain/Gilles Kohl
         Started: Tue 11-22-1994
         Subject: Test program - access SysMgr clipboard
         -------------------------------------------------------------------- */

      #include <stdio.h>

      #include "pal.h"
      #include "palsmsvc.h"

      #define CB_ERROR  "Fatal Clipboard Error\n"
      #define CB_EMPTY  "Clipboard is <Blank>\n"

      void read_cb( void )
      {
         char buf[1024];
         int TextIndex;
         int TextLength;

         if(m_open_cb() != CB_OK) {
            fprintf(stderr, CB_ERROR );
            return;
         }
         if(m_rep_index( CB_REP_TEXT, &TextIndex, &TextLength) != CB_OK ) {
            fprintf( stderr, CB_EMPTY );
         }
         else {
            int pos  = 0;
            int read;
            int retval;
            int i;

            while( TextLength > 0 ) {
               if(( retval = m_cb_read( TextIndex, pos, buf, sizeof( buf )-1)) >= 0) {
                  read = sizeof( buf )-1 - retval;
                  buf[read] = '\0';

                  for ( i=0; i < read; i++ ){
                      if( buf[i]!=0x0d ) putchar( buf[i] );
                      else putchar( 0x0a );
                  }
                  TextLength -= read;
                  pos += read;
               }
               else {
                  fprintf( stderr, CB_ERROR );
                  TextLength = 0;
               }
            }
         }
         m_close_cb();
      }

      void main (void)
      {
         PalInit(0);
         if(!CheckSysMgr()) FatalExit("SysMgr not loaded.", 1);
         read_cb();
         PalDeInit(0);
      }