Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/355.lha/post_v1.0/postmsg.h

C/C++ Source or Header | 1990-03-06 | 7.3 KB | 171 lines

/* PostScript interpreter file "postmsg.h" - message header file (Amiga)
 * (C) Adrian Aylward 1989, 1990.  Version 1.0
 *
 * You may freely copy and use this file.  It was written for Lattice C
 * V5.04.
 *
 * This file defines the message interface, so that other programs can
 * use the PostScript drawing machinery.  It is totally Amiga specific.
 *
 * To use the message interface to Post you first set up a named message
 * port.  Then run Post using the MESSAGEPORT option to specify the name
 * of the port you want it to accept commands from.  If Post loads
 * successfully, it will send a message action PSACTOPEN, passing the
 * address of its bitmap structure.  It then executes its startup file(s).
 * If they all execute without error it sends PSACTCOMMAND to request a
 * command.  If there is an error during startup it sends PSACTEXIT
 * instead; you should reply with PSCOMQUIT.
 *
 * Whenever Post is ready to receive another command it sends PSACTCOMMAND.
 * You can reply with one of the following:
 *
 *     PSCOMQUIT     Quit
 *     PSCOMRESTART  Restart - reinitialise and rerun startup file(s)
 *     PSCOMFILEL    Load a file
 *     PSCOMFILER    Run a file
 *     PSCOMSTRING   Execute a string
 *
 * (The other commands are for internal use).
 *
 * File names are null terminated strings.  Strings to be executed may be
 * null terminated, in which case you should set the length to -1, or may
 * have an explicit length.  You must not free the memory until the command
 * has finished; i.e. when you get the next PSACTCOMMAND message.
 *
 * There are two other messages that Post sends:
 *
 *     PSACTFLUSH    Flush out the bitmap, rows y1 ... y2 - 1
 *     PSACTPAUSE    Pause at the end of a page
 *
 * These may be sent any time Post is executing a startup file or command.
 * The command field of the reply is ignored.
 *
 * Not all the command line options are useful in conjunction with
 * MESSAGEPORT.  The INTERACTIVE option is ignored.  The SCREEN option will
 * cause the page buffer (i.e. bitmap) to be allocated from chip memory
 * rather than fast memory.  You advised to set the page size explicitly
 * instead of depending upon the defaults.
 *
 * You can either flush the bitmap into your own buffer whenever you receive
 * a PSACTFLUSH, or you can read/write it directly at any time.  Post does
 * not read the bitmap, nor does it write to it except to OR in or AND out
 * the bits that is drawing, so you can safely update the bitmap using your
 * own rendering routines.
 *
 * The default is for Post to allocate and initialise its own bitmap.  If
 * you prefer you can supply you own, using the USERBITMAP option.  Then
 * the PSACTOPEN message will supply a bitmap in which all fields but the
 * bit planes are initialised; you can must in the bit planes, or if you
 * prefer just change the pointer in the message to the address of your own
 * bitmap - which must be at least as large as the one initialised by Post.
 * It is your responsibility to zero the bit planes.  You must not free them
 * until after receiving PSACTCLOSE.  Should you fail to allocate the
 * memory, set the result field in the PSACTOPEN message to a non-zero
 * value; this will cause Post to exit with an error.
 *
 * In each message sent by Post the result field is set to the current value
 * of the return code; to zero if everything is OK, 10 if an interpreter
 * error occurs, or 20 if an error occurs during program initialisation.
 * When the reply is received, the return code is reset to the value in the
 * reply.  The errnum field is set to the internal error number of the last
 * interpreter error.
 *
 * The message structure bears a certain resemblance to an IDCMP message,
 * and can easily be processed by the same handler task.  It can be
 * distinguished from an IntuiMessage both by the class field being zero,
 * and by the window field being zero.  Post uses only a single PSMessage
 * structure, so its messages can also be identified by checking their
 * addresses.
 *
 * When launching Post you can use either a CLI or a WorkBench style
 * startup.  The CLI startup has standard input and output streams, which
 * you can redirect.  But the standard error always goes to the default
 * window, as Open'ed by "*".  The WorkBench startup has no standard streams,
 * so error messages will not appear in the window, and the usual error
 * requestors will be suppressed.  This may make it harder to work out what
 * is happening if something goes wrong.  However, it has the advantage
 * that the startup message is returned when the process exits, so if you
 * get the message back before a PSACTOPEN, you know it has failed to load
 * itself, and if you wait for PSACTOPEN you will wait forever.  In
 * practice, by far the most likely cause of any problems is lack of memory,
 * once you have checked that the required files (arp.library, ConMan device,
 * and possibly init.ps) are present.
 *
 * Various applications of the message interface suggest themselves:
 *
 *     An ARexx message handler
 *     An AmigaDOS PostScript device
 *     Display Postscript, for use by drawing programs etc..
 *
 * An example of a simple message handler is distributed with the release,
 * as the file "pmsg.c".
 */

/* Message structure */

struct PSMessage
{   struct Message ExecMessage;
    long class;            /* Always zero */
    short action;          /* Action - from Post to handler */
    short command;         /* Command - from handler to Post */
    struct BitMap *bitmap; /* The bitmap */
    short y1, y2;          /* Min and max+1 y values to flush */
    short result;          /* Result  (return code) */
    short length;          /* Length of string */
    char *string;          /* String */
    long window;           /* Always zero */
    short errnum;          /* Last error number */
    short zero;            /* Reserved, presently always zero */
};

/* Actions */

# define PSACTOPEN    1 /* Open */
# define PSACTCLOSE   2 /* Close */
# define PSACTFLUSH   3 /* Flush out the bitmap */
# define PSACTPAUSE   4 /* Pause at the end of a page */
# define PSACTCOMMAND 5 /* Get a command */
# define PSACTEXIT    6 /* Exit */

/* Commands */

# define PSCOMQUIT    1 /* Quit */
# define PSCOMRESTART 2 /* Restart */
# define PSCOMFILEF   3 /* Load Font */
# define PSCOMFILEL   4 /* Load File */
# define PSCOMFILER   5 /* Run File */
# define PSCOMINTER   6 /* Interactive */
# define PSCOMSTRING  7 /* String */

/* Errors */

/*define errdictfull             1
 *define errdictstackoverflow    2
 *define errdictstackunderflow   3
 *define errexecstackoverflow    4
 *define errinterrupt            5
 *define errinvalidaccess        6
 *define errinvalidexit          7
 *define errinvalidfileaccess    8
 *define errinvalidfont          9
 *define errinvalidrestore      10
 *define errinvalidstop         11
 *define errioerror             12
 *define errlimitcheck          13
 *define errnocurrentpoint      14
 *define errrangecheck          15
 *define errstackoverflow       16
 *define errstackunderflow      17
 *define errsyntaxerror         18
 *define errtimeout             19
 *define errtypecheck           20
 *define errundefined           21
 *define errundefinedfilename   22
 *define errundefinedresult     23
 *define errunmatchedmark       24
 *define errunregistered        25
 *define errVMerror             26
 */

/* End of file "postmsg.h" */