The functions in this module allow easy access to the Software Carousel Interface API. They all make use of the DOS INT 21H Function DFH Interrupt that is provided by Software Carousel and basically put a C wrapper around these functions.
Software Carousel is a product of:
SunShine Software Company 6950 Cypress Road Plantation, Florida 33317 954-581-2200
Contact SunShine by
SCPresent
: Is Software Carousel Present?
SCVersion
: Get Software Carousel Version
SCMenu
: Display the Software Carousel menu
SCSwitch
: Switch to another Work Area
SCQuit
: Terminate SC
SCBoot
: Reboot the computer.
SCKill
: Kill a program in a session.
SCSizeStatus
: Get Size and Status of a Work Area
SCSetSize
: Set a Work Areas Size
SCErrorMessage
: Convert Errorcode to Text
SCGetName
: Get a Work Areas Name
SCSetName
: Set a Work Areas Name
SCSendCommand
: Send Keystrokes to a Work Area
SCCodeMode
: Where is Software Carousel Running.
SCKeyboardCommands
: Enable/Disable Work Area Switching.
SCPresent
This command determines whether or not Software Carousel is
running. It returns the Version Number if present and 0 if not. #include "palsc.h"
int SCPresent( void ); 0 = Software Carousel not present.
Version = Software Carousel present. This call should be made BEFORE using any other Software
Carousel calls to determine if Software Carousel is loaded. int isschere( void )
{
/* variable to receive results of the function call
*/
int version_number;
/* do function to see if SC is loaded
*/
version_number = SCPresent();
/* display appropriate message
*/
if(version_number)
printf("\nSOFTWARE CAROUSEL version %d is loaded", version_number);
else
printf("\nSOFTWARE CAROUSEL is not loaded");
return(version_number);
}SCVersion
Returns the current version of Software Carousel
#include "palsc.h"
int SCVersion( void );An INT value containing the current version.
The SCPresent call should be made BEFORE using any other SC
calls to determine if Software Carousel is loaded. int ShowVersion( void )
{
/* variable to receive results of the function call
*/
int version_number;
/* do function to see if SC is loaded
*/
version_number = SCVersion();
/* display appropriate message
*/
if(version_number)
printf("\nSOFTWARE CAROUSEL version %d is loaded", version_number);
else
printf("\nSOFTWARE CAROUSEL is not loaded");
return(version_number);
}SCMenu
To display and activate the Carousel Control Menu from within
your program. 0 = success
1 = Error. Could not invoke menu. #include "palsc.h"
int SCMenu( void ); The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fMENU = 1, rc;
/* invoke the menu
*/
if (fMENU) {
rc = SCMenu();
if (rc == 0) {
printf("\nMenu Invoked");
} else {
printf("\nMenu not invoked");
}
}
SCSwitch
To command Carousel to switch to a different Work Area.
#include "palsc.h"
int SCSwitch( int session ); session An INT value containing the Work Area number (1-12) to
switch to, or the value (0) to switch to the next
sequential Work Area. 0 = switch was successful
1 = invalid Work Area number specified
2 = zero memory size Work Area specified The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fSWITCH = 3;
/* perform a session switch
*/
if (fSWITCH) {
rc = SCSwitch(fSWITCH);
if (rc == 0) {
printf("\nSwitched to session [%d]",
fSWITCH);
}
}SCQuit
To cause the Software Carousel Program to exit. Use with
caution as in-process information in Work Areas will not be
saved or updated. #include "palsc.h"
void SCQuit( int type ); type. INT value used to control "ARE YOU SURE" question and
display.
0 = ask & show program menu before quitting
1 = don't ask before quitting The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded.
int fQUITFAST = 0,
fQUITSLOW = 0;
/*......*/
/* quit sc without prompt
*/
if (fQUITFAST){
SCQuit(1);
}
/* quit sc with users permission
*/
if (fQUITSLOW){
SCQuit(0);
}SCBoot
This command permits your program to boot the system, removing
Carousel and all other software from memory. #include "palsc.h"
void SCBoot( int type ); type. An INT variable to determine whether to prompt the user
with the question "are you sure?". A value of 1
indicates booting without verification. A value of 0
causes the question "Are your sure?" to be asked for
verification before booting. The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fBOOTFAST = 0,
fBOOTSLOW = 0;
/* boot without prompt
*/
if (fBOOTFAST){
SCBoot(1);
}
/* boot with users permission
*/
if (fBOOTSLOW){
SCBoot(0);
}SCKill
To command Carousel to KILL the program running in a specified
Work Area. Note: This options also removes any TSR programs
loaded in the Work Area being killed. #include "palsc.h"
int SCKill( int session ); session. An INT value containing the Work Area number (1-12) to
kill. 0 = successfully killed
1 = Error. Invalid Work Area number specified
3 = Error. No active program in memory Work Area specified The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded.SCSizeStatus
To return to your program the size of the Work Area specified.
#include "palsc.h"
int SCSizeStatus( int number, int* size, int* status ); number. An INT value containing the Work Area number (1-12).
size. A POINTER to an INT variable, which will be updated
with the Work Area size.
status. A POINTER to a CHAR variable which will be updated
with the status (0 = idle; 1 = active).
0 successfully completed
1 Error. Invalid Work Area number specified
size The amount of memory allocated to the Work Area.
status (0) indicates that the Work Area is at a DOS prompt. (1)
indicates that the Work Area is not at a DOS prompt. The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fSIZESTAT = 0,
*size,
*status,
rc;
if (fSIZESTAT) {
rc = SCSizeStatus(fSIZESTAT, &size, &status);
if (rc == 0) {
printf("\nSession %d has a size of %d", fSIZESTAT, size);
if (status) {
printf("\n and a program is running.");
} else {
printf("\n and no program is running.");
}
}
}SCErrorMessage
For many API Software Carousel returns an error code. This
function will take that error code and print the corresponding
error message via printf. #include "palsc.h"
char *SCErrorMessage( int number );
An INT containing the Software Carousel Error Code.
An POINTER to a character string containing the Software
Carousel Error Message. The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded.
SCErrorMessage returns a POINTER to an 80 byte internal buffer.
If this call is made twice in a row the results of the first
call will be lost.
/* --------------------------------------------------------------------
PrintSCError: Printf's an SC Error message
-------------------------------------------------------------------- */
void PrintSCError(int number)
{
char *msg;
msg = SCErrorMessage(number);
printf(msg);
}SCGetName
To obtain the (menu) name of the Work Area specified.
#include "palsc.h"
int SCGetName( int session, char *name ); session An INT value containing the Work Area number
(1-12).
name A POINTER to a CHAR string field of at least 25
bytes which will be updated with the Work Area
name. 0 = successfully completed
1 = Error. Invalid Work Area number specified The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. char name[26];
int fNAME = 0;
if (fNAME) {
rc = SCGetName(fNAME, name);
if (rc == 0) {
printf("\nSession %d is called [%s]", fNAME, name);
}
}SCSetSize
To update the size of the Work Area specified.
#include "palsc.h"
int SCSetSize( int session, int size ); session An INT value containing the Work Area number (1-12)
to be modified.
size An INT variable containing the new Work Area size.
If the new_size value is larger than free memory
or Low RAM,this function sets the Work Area to the
largest size possible. 0 = successfully completed
1 = Error. Invalid Work Area number specified
4 = Error. Cannot change size of a Work Area with an active
program.
5 = Error. Invalid new size specified. The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fSETSIZESESSION = 2,
fSETSIZE = 512;
if (fSETSIZESESSION) {
rc = SCSetSize(fSETSIZESESSION, fSETSIZE);
if (rc == 0) {
printf("\nSession %d set to a size of %d kbytes",
fSETSIZESESSION, fSETSIZE);
}
}SCSetName
To update the (menu) name of the Work Area specified.
#include "palsc.h"
int SCSetName( int session, char *name ); session An INT value containing the Work Area number (1-12)
to be modified.
name A POINTER to a character string containing the new
Work Area name (maximum 24 characters). 0 = successfully completed
1 = Error. Invalid Work Area number specified The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded.
int fSETNAMESESSION = 2;
char szNAME[24] = "A PAL SESSION";
if (fSETNAMESESSION) {
rc = SCSetName(fSETNAMESESSION, szNAME);
if (rc == 0) {
printf("\nSession %d name set to [%s]", fSETNAMESESSION, szNAME);
}
}SCSendCommand
To send keystrokes to another Work Area.
#include "palsc.h"
int SCSendCommand( int session, char * cmd ); session An INT value for the Work Area number (1-12) to send
the command.
cmd A (zero terminated) string of characters to send to the
Work Area as keystrokes. Maximum size is 127 bytes, or
whatever you have set as the number of keystrokes to
pass through API, as defined with the SCCONFIG program. 0 = successfully completed
1 = Error. Invalid Work Area number specified
6 = Error. A previous SEND_PARTITION command is still pending
for the specified Work Area. Only one command can be
pending per Work Area. The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fCMDSESSION= 0, rc;
char szCMD[127] = "DIR C:";
if (fCMDSESSION) {
rc = SCSendCommand(fCMDSESSION, szCMD);
if (rc == 0) {
printf("\nSession %d was sent command [%s]",
fCMDSESSION, szCMD);
}
}SCCodeMode
To determine where Carousel code is running and being swapped
to. #include "palsc.h"
int SCCodeMode( int *mode );An INT whose bits have the following significance. bit 0 on = Carousel is running in Extended Memory bit 1 on = Carousel is running in Expanded Memory bit 2 on = Carousel is storing code in Expanded Mem bit 3 on = Carousel is storing code in Extended Mem bit 4 on = Carousel is storing code on disk.
The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fCODEMODE= 1;
if (fCODEMODE) {
rc = SCCodeMode( &fCODEMODE );
if (rc == 0) {
printf("\nCode Mode is [%d]",
fCODEMODE);
}
}SCKeyboardCommands
To control the operator's ability to use Carousel keyboard
commands; to invoke the menu or switch to another Work Area. #include "palsc.h"
int SCKeyboardCommands( int *type ); type. An INT variable used to specify the type of operation
requested:
0 = disable keyboard
1 = enable keyboard
2 = disable keyboard during AUTO-START
3 = get present status 0 = keyboard is disabled
1 = keyboard is enabled
2 = keyboard is disabled until AUTO-START finishes The SCPresent call should be made BEFORE using any other
Software Carousel calls to determine if Software Carousel is
loaded. int fKEYCOMMAND = 3, rc, fKEYCMD;
if (fKEYCOMMAND) {
rc = SCKeyBoardCommands( &fKEYCMD );
if (rc == 0) {
printf("\nKeyCommand Mode is [%d]",
fKEYCMD);
}
}